389COM: Code Quality
Dr Carey Pridgeon, DR Nazaraf Shah
Created: 2017-07-20 Thu 18:26
Why Code Quality Always Matters
- Style guides exist for a reason.
- Well written, non obscure code is more likely to be re-used by other
- 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.
- '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
- 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
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
- Trello is a good place to do this according to some of our past students.
- 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)