Somehow a lot of software professionals believe that my Mom will read this code. Or at least they want me to document it such that even she could read it. Why don’t they see the problems? There are loads of them.
- You are increasing body of text in the code, which, believe me, makes reading the code painful.
- The increased body of text will also make it equally tedious to debug.
- It takes hell lot of a time to document the code for a layman. There is a reason we do not program in natural languages, programming languages are a lot easier.
- It is equally inefficient and frustrating to spend time on keeping the documentation uptodate.
- Detailed text documentation can do unbelievable amounts of information overload. It is much easier to see the big picture using diagrams.
These are only some of them, if I spend an hour more I will be able to recollect another dozen or so from my memory.
Documentation is not evil. I document to record rationale behind certain decisions or to document the problem that the code solves. There might be cases where you are building an API and you want to document it to save someone the trouble to read through the code, and this usually contains what it does, not how it does something. But repeating what the code does is nothing but duplication. I hope that the code is read by a programmer, who has taken the minimum of effort to read up on the language it is using. And if he/she wants to do anything more than that, he/she will acquire the skills. There is no point in documenting to play to any other profile, including the upper management executives.
And if you do want to communicate to a layman, user documentation is what is needed, that uses non-technical terms and explains benefits of the software, not how its code works. Use documentation to help you build better software and continue working on it, or be prepared to get killed by it.
March 11th, 2008 at 12:17 pm
Hi Abhijit,
You have banged the nail right on the head. The non-technical management often overemphasises documentation, but there cannot be more precise documentation than the code itself. The nature of programming languages is such that the written code presents the logic of the software in unambiguous manner. Otherwise the code will not work. Therefore the emphassis must be on well-written & structured code, so that the next technical person who is the real user of code can work on it.
Baji
March 12th, 2008 at 6:29 am
I base my post on what I have seen as a Java Enterprise engineer in the Tampa Florida area.
Documentation is very important. Do we need comments on POJO getters & setters? No, unless some special manipulation is being done within one of those methods (which I believe belongs somewhere else). It is very difficult to take a software project forward when the last round of developers left in mass and the code was poorly documented. I think it is lazy to not add code to important parts of any code. I use a medium level of documentation because when a developer needs to work on something I created, I want that developer to succeed and not be cursing my name.
Regards,
Tom
March 12th, 2008 at 7:12 pm
You have to joking. TELL me you are joking. You mother may not be reading the code, but if you are a growing team that may hire some newer programmers, they’ll be reading your code. They’ll probably put on the “testing team” that has to write tests for your code. Good documentation will tell that junior programmer what your code is suppose to do and give clues as to how to test it. You do test your cod right?
For instance, large financial company, lots of processes and procedures in place unique to that company…different terminology, etc. You go in and try to hit the ground running with code. Without good documentation, you’re going to waste alot of your time answering any newcomer’s questions. You’re a fool not to document code and we should all get better at it. NO you DON’T have to repeat your code in plain english verbatim, but at least give them something. Why the hell do you think they have javadoc tags for?
Here’s my little bit of intuition hitting me. Your firm has scored some project from overseas, (most likely the US because we’re a bunch of cheap bastards)…you wrote code that wasn’t clear, wasn’t concise and wasn’t good. They came back to you asking you to document what it is your code is doing so that the real programmers over here can fix it or more than likely rewrite it all together.
Sounds to me like you’re just being plain lazy. Are you really that worried about how many lines of code there are? And how does it affect your debugging? Comments are ignored man…and have no effect on how well your application performs…
March 12th, 2008 at 7:26 pm
The name of a method should summarize what the method does. The body of the method, written in terms of calls to other descriptively named methods, explains how the method does what it does. The documentation of the method explains why it is done that way instead of some other way, and any caveats (i.e., boundary cases for which the method doesn’t work).
March 12th, 2008 at 8:08 pm
Thanks for your comments.
Tom, I agree with you that the other extreme of verbatim documentation does not serve either. Like I said, I use documentation for many reasons, but not to say how the code works.
Ryan, as I said, I do document, but not the code. Believe me, there are comments in my code. Is documenting how the code works going to help the junior programmer with the tasks? Isn’t it more important for him/her to understand the code and not just the documentation. I agree with you that in case that junior programmer is an user of your API. And don’t worry, this post is not a way to escape documentation, I know better than that. This post is an old rant, when I realized that I had spent more time documenting the code than writing it. I had just forgotten about it completely and pushed it when I saw it today.
Frank, I would prefer to write code which itself conveys what it does instead of having to document it. I agree with you that the caveats need to be documented.
March 12th, 2008 at 11:23 pm
I can’t imagine that you’re asking us to stop commenting. That would be silly–bordering on negligent–advice.
Personally, I write block-level comments for a method before I write a single line of code. This serves three useful purposes.
-First, it allows me to work out the logic before I start coding. If the logic doesn’t work out, I find that changing comments is always easier than rewriting code.
- Second, anyone can read the comments first, and understand the method’s logic without reverse-engineering the code.
- Finally, the comments provide my intention for the implementation. If the two don’t meet in the middle, the problem is immediately clear.
The last point is critical, because you can’t reverse-engineer intention. If uncommented code is doing X, how do you know that it shouldn’t be doing Y? Or Z?
March 12th, 2008 at 11:59 pm
B. Waite, I never said that we should stop commenting. If you read the post, I do say that I use documentation and I use comments for different purposes.
What I am against is using comments to explain what the code does. If it is going to be read by a programmer, then isn’t the code enough? Can’t we write code that can convey its intention? As I understand you use comments to write the pseudo-code, which all of us need. But is it necessary that it goes in the comments?
Secondly, if I am reading code, then why do need to reverse-engineer it to understand the logic? Shouldn’t we aim for code that is self-explanatory?
I agree with your third point. I write comments to convey the problem the code is trying to solve.
March 13th, 2008 at 7:51 pm
commenting what it does will indeed help out:
In larger complicated projects that have had numerous developers in and out, numerous iterations and ongoing integration, you’re going to want to generate the browseable javadocs and use them as a reference. You may be asked to put out some “fire” so to speak in an area where you’ve never been before. You can fire up the browseable javadocs and assuming there is good documentation about what the code is doing, you can read it right there.
Granted, your more advanced programmers are probably just going to jump right into the code and start hacking away. I’ve seen the screw people in the long run because they mis-interpreted the code. The learning curve of that companies terminology and their processes combined with the more junior level experience caused others a headache. Had there been some clear and concise documentation there to read, we could’ve saved that headache. I see no reason why documentation hurts.
Are we not craftsmen? Or are we just code monkeys? I hope you’re a craftsmen who pays attention to detail…even the mundane, boring details.
March 18th, 2008 at 9:29 pm
Ryan, thanks for continuing the discussion. I fully agree with you that an API warrants documentation, but targetted towards its users, not its developers.
I agree with the craftsmen part 100%. That is one of the reasons I believe that we are capable of writing comprehensible code, which does not require documentation’s aid to explain how it works. At the cost of repetition, I say that I am not shunning documentation entirely. I believe in diagrams, I believe in API documentation, I believe in putting down the intent. I consider translating the code into English for documentation is a waste of time, it is not required for code that is comprehensible. Otherwise documentation eats up a lot of time and effort, and that I believe hurts the project.