389COM: Code Quality

Dr Carey Pridgeon, DR Nazaraf Shah

Created: 2017-07-20 Thu 18:26

Why Code Quality Always Matters

Readability

  • Style guides exist for a reason.
  • Well written, non obscure code is more likely to be re-used by other developers.
  • Compilers can turn any well structured code into a good program, so there is no reason at all to make your code hard to read.
  • Potential employers are more likely to be impressed by well structured code.
  • Comments!!!!!
  • 'I can understand it so other people can too' has never been a valid viewpoint. It has always just irritated me.

Appropriate design choices

  • In open source coding, especially at the start of a project, there is no rush.
  • Choose the right Language.
  • Choose the right programming methodology OOP, Procedural, Functional.
  • It matters more that the chosen methodology matches the problem then whether or not it is in vogue. Personally I don't like OOP, but I use it if it is appropriate for a given task.
  • Have some design ideas, and make them visible to others in your repository, write some User Stories, put these online in your repository too.

Documentation - 1

  • This is probably the biggest problem in open source development.
  • Why is it worse for open source then it is for the commercial world?
  • Why should avoiding this problem be a priority for you?
  • Automatic Documentation is a thing, and has been for decades, so there is no excuse. Nor if you use it, is there an excuse for using it badly.

Documentation - 2

  • Wiki pages (gitlab/github et al provide these) are a good place to provide documentation not suited to automatic generation.
  • Auto documentors collect up comments from your code, so using them will encourage you to get into the habit of writing information rich comments.

Documentation - 3

  • There are some good open source auto documentors available, I recommend you try Doxygen
  • Avoid static documentation formats (hand coded web pages), as these are far too difficult to maintain.
  • The websites and materials used on this module, and in all my teaching, are auto generated from plain text via org mode in emacs, even most of the diagrams.

Testing

  • What do we mean by testing code.
  • When do you start testing.
  • What testing approaches are there?
  • Discussion point: Why is testing one of the highest paid positions in software engineering?

Bug Tracking/Fixing - 1

  • If you don't use an online git repository, your code will essentially be invisible.
  • 'Many Eyes' Principle is only true in theory. In practice it's only true for either very large or very populer projects.
  • All Bugs need to be reported in your online documentation. Both gitlab/github both have 'issues' functionality to facilitate this.
  • All work to fix them, successful or not, must be reported in 'issues', because of the potential employer visibility aspect.

Bug Tracking/Fixing - 2

  • Bugs aren't really significant externally till you get to tentative release level of development, although for shared development.
  • Non trivial bugs still go in issues.
  • For shared development, planning and timeline management should also go online.
  • Trello is a good place to do this according to some of our past students.

Obligatory XKCD

code_quality.png

  • Copyright: Randall Munroe - XKCD
  • Mirrored in my hosting to avoid bandwidth stealing

Licence for this work

  • Licenced under Creative Commons Attribution-ShareAlike 4.0 International by Dr Carey Pridgeon 2016
  • (Licence does not cover linked images owned by other content creators)