This is one of the great discussions among developers: document or not document your code? Is it worth writing documentation in your code?
I thought this topic was completely overcome and it was clear that, except some few occasions (implementing a public API), documentation was not necessary. Until I saw a code review where the reviewer pointed out the lack of documentation as an issue. Really?
I was one of those who used to document my code... or at least I tried. I was so convinced that code had to be documented. As a backup or reminder for my future myself or any other developer luck enough to end up in my code. Although I always realised it was always out of date. And by then, I already wondered: what is the purpose of documenting the code if the documentation is always outdated?
Until several years ago I read the book Clean Code.
I saw it "crystal clear", there is no need to document your code if you code your documentation.
With this I mean to use meaningful variable and method names. If the name of the member already tells you the information that is keeping and the name of the method tells you what the method is doing you can end up reading the code without the need to figure out or document what your code is doing.
Extract as much code as you can to methods. Even if you end up having a method with only 3 or 4 lines. Each method should do one thing and only one thing. And the name must explain what it does.
Each member of a class must have a name that only reading it you know which information you can find there. Same for variables and input parameters.
Following this simple steps you can have a code you can read, having the documentation right in the same code.
Yes, I know, there are those times you have to implement code with a complex algorithm or you are copying a code you found on Internet which might be complex, you might not understand and you might not extract in simple and meaningful methods. Yes, there are always exception.
What do you think? Do you document or write the documentation in your code?
This post was originally published in Medium
Latest comments (34)
I think that the only documentation needed (if you wrote clean code) is for public apis that need to be used by clients. And only comment todos if you are coding in a rush and you need for sure that you will be refactoring a part of your code asap.
Don't code your documentation. Code what you test, document the tests.
Good point ! Someone here can link to some code that doc correctly, the WHAT and WHY. It Will be very useful for a JR dev like I (:
My opinion in general, you can't code documentation, the source code is the what and not the why. So as always, it depends :)
I think this has been settled for years - write code that documents itself as you describe, and add documentation to explain why, for instance, you're suddenly doing something that seems unnecessary.
Writing documentation is a pretty thankless job. Nobody will ever read what you write and no matter how much of it you write people will find something you did not document and complain about it. It's always somebody else that ought to document something. And somehow it is frequently implied that would be me.
So,my attitude to documentation is "by exception". Most code should be obvious and not in need of any documentation. But once in a while you do something non trivial and then it matters to document wtf. you were thinking. A simple link to a stackoverflow post to explain the totally non obvious workaround for some issue, the weird set of circumstances that caused you to add some null check or other condition that you chased down, etc. Those are the things that need documenting. All the rest is obvious.
I love little hints that outline the reasoning behind bits of non obvious hackery, algorithm choices, concurrency handling and other bits of code where somebody really went the extra effort to get things done the right way.
Great post!
When I first got into development I was really confused by the concept of not adding documentation to code. In school I was taught to always comment everything and always have documentation in code. On top of that I worked as an automation engineer for a while where each line had to be commented to explain what it was doing. Which in hindsight, was terrible to read and scan.
I understand this concept now and really it's just easier this way. The only time comments are really added to a project that I've seen are when a special work around is added for a bug in a library (external dependency), which includes a TODO to come back and update the code when the bug is fixed.
For me and the company I work for, we document our functionality and how API's are supposed to work in a common space that isn't in code.
I absolutely agree with that. But you could take that to the next level. E.g. If you need to document REST interfaces, you could just write a document, wiki page or whatever. But that's similar to writing code comments. You could use some annotation based documenting framework, but you're still able to annotate any response code that does not have to match.
So we wrote a litte tool that captures requests, responses and additional textual information during test execution.
You're forced to have at least one test covering each use case and when all tests are green, you've got an up to date REST documentation as markdown.
I like to document my code inline as soon as it becomes non-obvious on first glance. I specifically write a small comment on each "branch" the code may take by an if/else distinction. Generally, my code should be easily understandable by people who have mastered the language its written in but have no idea what my software itself is about.
If my method names have speaking names, I like it and I'll make use of it. But as far as I have tried it, kind of more often than not this is not possible without introducing the lengthy gibberish names we have to deal with in Java or C#.
I like to document my code inline as soon as it becomes non-obvious on first glance. I specifically write a small comment on each path distinction the code may take, introduced by if/else. Generally, my code should be easily understandable by people who have mastered the language its written in but have no idea what software itself is about.
If my method names have speaking names, I like it and I'll make use of it. But as far as I have tried it, kind of more often than not this is not possible without introducing the lengthy gibberish names we have to deal with in Java or C#.
A problem with depending on your function names for documentation is that it makes your code rather verbose. (Anyone who has been a Java for dev for any length of time knows exactly what I'm talking about!) Following the logic of Clean Code, I suppose that
mapshould have been namedapplyFunctionToAllElementsor something. Fortunately though that isn't the case, and after reading the documentation you can remember whatmapmeans and be spared all that verbosity.I'm not against favoring code over comments though. If it's a private method that has a very specific purpose and isn't called from many places then I'm happy to not give it a comment header. As ever, "it depends".
Whenever I found naming hard, I realised had an incomplete idea of the domain and goal.
I have a number of challenges for people who think code can generally be self-documenting. The first one is to code the quicksort algorithm in such a way as to make the average and worst-case time complexity obvious, and also explain the circumstances in which the worst case occurs.
I do both. Saved me many more times I care to remember.
Sure, name functions and variables in a meaningful way but put a comment block at the top of the function to explain the what, why and how.
Taken further, try this method (it's what I do and often commented upon in a welcomed way):
Like tests, comments are best written before the actual code but they must be reviewed after the code is written to ensure their value.
There are a few reasons why I consider comments important:
Both! Use meaningful variables to help define your constructs but also explain your thought process in comments. As someone who as written code and fixed other people's code nothing helps more than "// this loop examines each item in the array looking for the process flag" W00T! I now know why this loop exists!