In my previous post, Coding Standards Revisited: Writing Code That Lasts, I talked about how to approach a code review from a slightly different perspective. Today I'd like to talk about approaching coding standards from a slightly different perspective.
As I mentioned in my previous post I find a lot of value in framework, language, or platform specific coding standards. But I do not believe they tell the whole story. Here's a short list of non-traditional coding standards that I believe apply to all code on all (modern) frameworks, languages, and platforms.
Use meaningful variable, method, parameter, and class names. DO NOT use shorthand. A person that does not know how to read code should be able to tell you what the variable, method, parameter, or class is doing just from the name.
Separate out your concerns
A method or class should have one reason to change and ONLY one reason to change. If a particular method in that class has more than 10 - 20 lines it's probably doing too much. There are very few exceptions to this. Methods and classes should be distinct features that overlap in functionality as little as possible.
Write highly cohesive classes. The methods in a class need to have a lot in common. The methods in a class should act on the same data. The methods in a class should all be related to the data. I.e. an image manipulation class that has code to physically save the image to disk is not cohesive… it's coupled. There should be a class that deals with saving things to disk and a class that deals with image manipulation.
Dependencies should be added by reference as much as possible and injected into the classes that depend on them. This allows the dependencies to be created at the correct level of abstraction.
High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend upon details. Details should depend upon abstractions.
Don't Start By Abstracting
Only abstract as you need too. The first (and I would argue second) implementation of something should come in the form of concrete classes. Only when you run into a scenario where you need to interchange these classes should you then abstract it.
Follow the Don't Repeat Yourself (DRY) principle. Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.
Commented Out Code
Don't comment code out and leave it. Delete it as you can always go back to it using source control.
Only Write Enough Code To Satisfy What You Need Now
Don't write a single line of code for something in the future (i.e. I'm gonna need a class that….). Only write code that is actually used right now for what you're doing. Usually for me, this means starting with a test class. In the case of a UI I usually start by writing static UI Code and then working backwards making the code dynamic as I go and ensuring that each piece of dynamic code as a set of tests associated with it.
Yo - congrats.ReplyDelete
And by that I mean, "I'm pretty sure you're inadvertently - or possibly on purpose - working your way towards a book, and I think at the end of the day (i.e. year or two) you will have it."
SO: If you *are* writing a book, or working your way towards it, let me know - I'm a damn good editor, believe it or not. ;) And if you're *not* planning on doing so, I think you should consider it - you've already got yourself a few "chapters" here that could easily be expounded upon, and I'm guessing you're far from done with this Software Craftsmanship topic anyway...
You've read my mind. I was actually just taking about this the other day. Once I get a draft together I'll make sure you get a copy!ReplyDelete