I’ve been developing software over 30 years, 15 of those professionally. I’ve learned a thing or two from the real-world trenches, one of which is that all code written must eventually be maintained… probably by you. The more you can do to ensure your code can be understood 6 months (or more) later, the better (your) life will be.
But this is hard.
Not just whining that it’s hard, but it is a difficult thing to do because who can know what exactly you’ll need to know or care about during maintenance. And while you’re in the heat of the moment writing code, you may not consider everything that needs to be documented. This is why the best you can do is strive to write simple code, well-factored, and as understandable as possible from the get-go. Premature optimization is the root of all evil. Simple is good; simple is best.
Is it good to have coding standards? Yes it is. I think all coders should have their own set of standards and stick to them. Yes you can evolve your standards, but still you’re having formal standards. Should everyone on the team/project be bound by those same standards? Not necessarily. I had a job where they wanted to lay out edicts for how all code should look. The standards wound up being the vision of one person’s personal style thrust upon everyone else. This was inefficient because now instead of worrying about writing my code, now I was worried about writing code that conformed to the standard. Code reviews were less about finding true problems in code and more about conforming to the standard. This is not how things should be. Frankly, I’ve found it useful to let people code in their own style because they are more efficient that way. You’ll always come across code that isn’t yours and isn’t written the way you like it — deal with it, because the world cannot and will not conform to you. Furthermore, it’s useful that each coder has their own style for it acts like a signature. Who wrote this code? Ah… based on the style, I can tell Joe wrote it so we can blame him.
However, if a coder on the team has no style whatsoever, or their style is erratic (the style of no style, and I’m not talking the higher Bruce Lee-like style of no style), that can lead to sloppy, unreadable, unmaintainable, error-prone code. In such a case, it’s generally been better to have the person work to find their own style and establish some sort of style. If they want to use someone else’s style as a base, that’s fine to help them find their own way. In the end, it really shouldn’t matter what someone’s style is, so long as there is style and method to the madness.
Standards have their place, but you must remember the purpose of the standard and not let the standard become the overriding concern. In the end we want code that people can work with and maintain, and IMHO so long as we achieve that we’re doing fine.
Clever Code, Comments
Clever code isn’t necessarily a bad thing, but you must know when the code is being clever and document it. Realize that not everyone may be as clever as you, but more than likely when you have to come back to this code down the line you yourself are unlikely to remember what was so clever about it. If the code is clever and truly works to be a better way to implement things (instead of being clever for clever’s sake), then go for it but ensure it can be maintained. This is where comments come in.
I do not like people who say code should be self-documenting and leave it at that. Yes, code should be readable and make sense. It’s better to name a function
calc() and certainly proper naming of functions and variables can help make code readable and understandable. But all this can tell you is the “what” of what’s going on. It cannot tell the “why” of the code, including why it may have been written this way instead of some other way. Comments are a vital part of coding, and if someone isn’t going to take the time to read them then that’s their fault as a poor programmer.
However to make comments worth reading, the comments should be… well… worth reading. For instance:
// Add x to y
y += x;
That comment was unnecessary. The code tells you that already.
// Add x to y to work around a compiler bug. It'd be
// nice if the compiler had a version preprocessor
// directive so we could detect a new version and then
// retest to see if the bug was fixed, but alas it
// doesn't. Thus we shall track it in our bug database
// as issue #153484
y += x;
There the comment is used to explain something non-obvious, the “why” of the code.
Some say comments should be kept short, and generally I agree. In our world of “tl;dr“, it’s best to keep it brief, but don’t make it brief just to satisfy those too lazy to read. Sometimes you just have to explain. One project I worked on years ago had weaved a tangled web of ownership over a particular resource. I was attempting to clean things up but the more I investigated the worse the tangle became. In the end, there was no way to untangle it without a complete rewrite of a significant portion of the application, which wasn’t going to happen, thus we had to leave the mess alone. I opted to document the problem in code, and the comment block ended up being a few pages long — the problem was that ugly. It needed to be documented to save someone in the future from breaking the fragile mess or going through the same pain all over again. A few years later I got to speak with the new owners of the codebase and they recognized my name from the monster comment. We had a good laugh over it and they were appreciative of the documentation. See? Some people do read comments.
One small other thing. When you comment, document the comment. I find at least a name and date/time stamp are good. Set up a macro or a script or some other bit of functionality to figure it out and automate it for you. Then it’s a single keystroke to insert the comment stamp. If you don’t see the value in this, try it for a year then reevaluate.
Building on the above, I’d like to revisit style for a moment.
One thing that makes Cocoa programming different from some other modern coding toolsets is Cocoa imposes a lot of style upon you. There are a great many things Cocoa does in terms of functionality and design patterns that actually build upon the style of your coding. It does annoy some people, but the reality is that life is better when you do adopt Cocoa’s style. Things like Key-Value-Coding and Key-Value-Observing tend to work out better when you accept and follow the Cocoa coding conventions.
The helpful part here is to program in Cocoa you generally end up using a new language in Objective-C, which due to its funky syntax somewhat requires you to find new coding standards anyways. Thus, just accept the Cocoa standards. It really does work out better towards making that Cocoa toolchain work most efficiently and allow you to develop good software, faster.
I mention this because I’m presently working on a project where they are using Cocoa, but they aren’t really using Cocoa. Yes they are using the language and the frameworks, but not to their fullest potential. Furthermore, some code is written distinctly against the grain of the Cocoa style. Not only does it make for difficult to read code, but it can cause future problems for the usability and maintainability of the code.
While I do generally say you should just go with your style, also understand what the greater goal is. If your goal is to write good software, sometimes the overall toolchain functions better when you use the tools as they were intended to be used and not imposing your own way of being upon for whatever arbitrary reason. Tools are there to help you, use them in their intended way.
It’s another reason I like Python as a language. I learned Perl and while I appreciate the power of Perl, it made my head spin. Perl code can be rather obfuscated (in fact, it can be celebrated), and for the casual user it was difficult to work with Perl. I’m happy for my O’Reilly books, but constantly looking things up really slows down development. So I left Perl behind and went to learn Python. I couldn’t be happier. The main reason? Python strives to be simpler in syntax, allowing a lot of power but also putting some constraints on style and functionality. Perl is about “there’s more than one way to do it” and while that can be useful, I’ve never found Python’s constraints to prevent me from solving a problem. Others agree: here, here, heck… ESR agrees too.
Coding practices are important. There needs to be some sort of structure to make things go. Some languages and toolchains even understand the value of this and work to impose some modicum of structure, usually to positive benefit.
But to force and impose standards and style has limits. We have to remember the intent is to allow people to write good code, which means code that isn’t just functional and solves the problem, but is also maintainable. It takes time to find your style, but you must seek it out. It will allow you to write better code, and those who work with your code will think so too.