Brandon Savage has posted a few suggestions about dealing with coding standards and how they can help improve the quality of your code via his refactoring of a bit of example code. This time the focus is on documentation.
One of the first things I look for when I check out code is how is the code organized? Is it laid out well? Is it coded to a particular standard? In our code sample, the first thing we should address is how does the code look. There are a number of suggestions I would make immediately.
His list includes four suggestions for/comments about different areas of his example code:
- There are no DocBlocks or clear coding standards
- Examining The Properties (comments of the class properties)
- Conditionals (changing inline to braced)
- Improving The Constructor (to make it more flexible)