I know this is going to be a very controversial article, but I'm going to write it anyway.
Self Documenting code is not a good goal to aim for. Quite the opposite in my opinion.
Comments in code exist for a number of reasons. One of those is to tell what code does, and this is the kind that Self Documenting code seeks to remove. This is not a bad goal, because if the code needs comments to tell you what it does then it's too complicated.
Another form of comment, though, is the one that tells you why code does what it does. This is much more important that what because this is not self evident from the code itself. This can come down to code design decisions, product design decisions, large scale architecture decisions, or a myriad of other reasons.
Yet another form of comment is links to external sources. This can be issue tracker numbers, design documents, or many other things.
Finally, sometimes you really do need to document the big picture of how something works, because the entire algorithm is complex and it's not feasible for everyone to read all of the code to get the big picture overview.
So, whilst striving to make your code clean, obvious and easy to follow, don't go to far in removing all code comments because they have other uses too.
Latest comments (33)
Comments are useful for explaining rationale but not much else.
If the code doesn't explain what it's doing then it's poorly written. Because most languages can be written in ways that are incredibly easy to read.
There seems to be an almost macho trend, especially in the FP world to try to write code that is demonstrably not readable and pretend like it is.
I hope that trend dies because its a nightmare.
In copied code snippets I often add a comment of the URL where they came from, such as GitHub or Stack Overflow.
The right three line comment can tell me as much as reading 50 pages of code. The 'no comments' absolutists are a mystery to me.
I like to document code blocks, for example big bold:
/*
and so on... it helps readibility and quick finding stuff
Code can replace most "what comments" but it certainly cannot replace the "why comments". In addition, there are some "what comments" that are needed because they explain what a complex stretch of code does.
Yep exactly this!
Although I'm still in university, they really drill us to comment our code in academia (obviously for good reason so we know what we're doing). Three years into this degree though, I find myself using comments only when I'm writing something that's too complex to speak for itself. For example, just recently in my Object Oriented design class, we're told that making variable and function names that are verbose (i.e in Java: IndexOutOfBoundsException; There's really no need to comment on what that exception is. Sure it might be a little longer than what's maybe seen as typical length, but it's to the point!) I find myself frequently looking at this example when I'm writing code.
That being said, I recently had an interview where a potential employer saw some of the code I've wrote in the past and specifically mentioned on my lack of comments, and I told him what I had just explained above. He responded by telling me that it's not about me, it's about the people after me.
I'm not sure, as a community, developers will ever create a universal standard for commenting, but one day we can only hope.
I think you’ve hit the nail on the head. I worked on a team that disliked docblock comments (and would fail my code reviews if I included them). Their rationale was that any amount of commenting would allow a developer to become lazy when naming methods and variables, or wouldn’t extract functionality out. While I agreed on some level, the wholesale refusal to merge code that contained any comments at all seemed overkill. All too often I stumble across code that appears to be doing something odd, or a “better” solution is very obvious to me in that moment. In the rare cases that I’m able to discuss those past choices with the original developer, the reasons why are usually illluminating. Being able to communicate why something needs to be done seems like the best middle ground available, and is something that I try to be mindful of when I’m authoring or refactoring code. Good article.
Self Coding documentation?
Because that is a very interesting idea.
Sadly, best practices/patterns/anti-patterns are often applied without understanding the problem they address.
And the solution seems to be similar in most cases: Understand why the best practice/pattern/anti-pattern is one, what the tradeoffs are and what that means for the specific case. Easier said than done, I admit.
In this case, There are some comments that are inherently important (why-comments) and some that are incidentally important (what-comments).
What I would prefer to do:
Graham, Yes and no. I do incorporate self documenting code as the structure for the coders to use. There is always overhead stuff that needs to be in place. I encourage the coders to full document code.
Most arguments against comments tend to implicitly assume that code can always also express why, despite the requirement to implement weird business rules being pretty much a/the staple of software development.
Many often believe that writing comments is an absolute waste of time, and that our only concern should be to have as clean code as possible.
I am a great fan of comments that focus on why or how, instead of what, and here lies the big distinction:
On the one hand, what a piece of code does, should be apparent from the code itself. Too many lines, difficult to understand syntax or poorly named variables are all signs of poorly written code.
On the other hand, why or how this code does a specific thing is a matter of the business logic of the application, and should be documented.
One cannot expect from a developer that opens a file to have a full grasp of the app's business logic.
Keep in mind though, that clean code means clean comments too and also requires extra effort to refactor and keep these comments up-to-date as well. :)
I have to tell you that when I read the title, I was on the defensive. That was short live when I got to saying comments should tell "Why" not what.
Telling why keeps the next guy from removing/changing code that looks unneeded or unclear to the reason it is there.
Good job!
Code is written for other developers to read. If they can't read and understand code, they should not have the job. Code should always be self documenting by use of variable names, anyway. That should be stressed. Your verbiage does not do that. Of course, a comment can be added when necessary for unusually complex code, but most of the time is not needed.
Most people do not document. Are you going to be a moralist or a computer programmer. To obtain at least some documentation, stress and require self documentation.
ASCII art is a good use of comments, e.g. drawing a hidden-line diagram of a cube with the corner and mid-side node numbers since for FEA programs there are at least 3 different conventions. Typically this will be for processing by Doxygen.