Your Code is Not Self Documenting

http://progfu.com/post/2668280164/your-code-is-not-self-documenting

by darthdeus • 16 years ago

31 25 16 years ago

wccrawford• 16 years ago

Every comment there disagrees with the post. Were you hoping to come here and find people who will agree?

I also disagree with it. Good code is as self-documenting as possible. Any gotchas should be explained in comments, but correct naming is way more valuable than comments explaining what a function does.

Any code that fails to be self-documenting needs to be refactored immediately.

erikb4• 16 years ago

To follow the ongoing culture of disagreeing, I disagree with you that bad code needs to be refactored immediately.

That has a technical reason: "Don't touch a running system." You know, you can never be sure what you change there, if the code is really that bad.

And it also has a management reason: Everything these days is about efficiency. You only have a limited amount of resources. That might be coders in your company, when you are the CEO. That might be free time, when you code for yourself. But all these resources should be spent wisely. So, if refactoring the code takes a lot of resources and the functionality of the software actually stays the same, I would suggest to do that later, when it really needs to be done because you need to change the functionality. And if it is selfwritten code, it might be smart to go on with the next project and improve your coding quality through more experience over time and maybe later come back to refactor.

lelele2• 16 years ago

> That has a technical reason: "Don't touch a running system." You know, you can never be sure what you change there, if the code is really that bad.

My experience has been that "Don't touch a running system." takes you to "How the heck does this thing work?". And every time even little fixes get hairy and time-consuming. It's kind of when you listen to people justifying their untidiness: they say they do know where to look for things. Yes, they do know, I'm sure, but can they find those things quickly, especially when "the shit hits the fan"? Does their approach work when their lives get more complex? How would they score against people who keeps things sorted and plan ahead? I have been a pretty untidy teenager, using these very same lame excuses, but nowadays I can't afford it.

skybrian• 16 years ago

Yes, there's particular style of code called "self-documenting." It's a good style and I recommend that everyone learn it. However, it doesn't do everything. It's good at explaining what happens and how it happens but not why. Comments are for explaining why. Without knowing the original programmer's intention, I'm still mystified.

lelele2• 16 years ago

> Comments are for explaining why.

Awesome. I'd add "why not" as well, that is: why you discarded some alternative solution? That's very important especially when refactoring is involved. Some programmer could come by and think: "Why she didn't just do like this? It would have been much easier."

I find that explanations about discarded solutions is (almost) always missing from both comments and higher-level documents.

sliverstorm• 16 years ago

I'm not going to argue that you should not document your code, but two things come to mind:

1) With the backup example- you have indeed moved complexity elsewhere, but the idea of that kind of setup is you logically separate complexity into a hierarchy so that the proper segment can be rapidly located, and is easy to comprehend because it is isolated, and small chunks of complexity are not all that hard to understand.

2) Every example of well written self-documenting code I've ever seen is pretty much superior to the alternative in every way, with the possible exception of small performance hits. It's generally a good goal to shoot for, whether you document your code or not.

ShardPhoenix• 16 years ago

I don't think every function needs a comment, necessarily, but I have seen "self-documenting" used as an excuse for not documenting anything at all. It's easy to declare code understandable and readable when you're the one who wrote it.

j_baker2• 16 years ago

Fair enough, but that's kind of orthogonal to the author's point isn't it? An idea isn't wrong just because it can be abused.

dwc• 16 years ago

I've also seen that used as an excuse, along with almost everything else you can think of. We've all seen the results of "I'm adhering to each and every rule but coding how I want anyway" coders.

rnemo• 16 years ago

Agreed. While the author tends to take the viewpoint that attempting to write self documenting code is almost a bad thing, and that's very wrong, I understand his frustration, because too many programmers these days seem to think that documentation in the comments are either superfluous or a sign of bad code, and that's also just flat wrong. It's a shame that the author takes the opposite extreme.

Like most things in life, code documentation requires balance, and one should strive to create code that is easy to read and understand, but good code cannot be easy to read and understand in all circumstances, and comments should be used in any situation that confusion could possibly arise.

For my own code, aside from commenting on obviously confusing sections, I tend to create functions that have an easily understood purpose when called, but I tend to use 1-2 lines of comments when I declare the function so that I can feel reasonably sure that anyone reading my code wont have too many questions. I've found through feedback that this is a fairly functional method of documentation.

Jach• 16 years ago

Perhaps not, but I don't think inline documentation is often very useful either and breaking code density is a jarring thing. External documentation exists for a reason (even if it's just doxygen-izing your inline docs instead of pointing people at the direct source), and I much prefer reading (and writing) short READMEs, examples, or tutorials than digging through implementation code if I'm interested in using something. And if I'm integrating anything non-trivial I don't think little comments saying "/* * executes the passed query string, not using prepared statements, throws SQLException, returns nothing */ public static void executeSql(String query) throws SQLException {" are useful or worth my time. Write comments when something needs some explanation not clear from the context, save the academic comment-everything documentation for enterprise busywork or academia.

beoba• 16 years ago

I think you're mixing up inline documentation with api documentation.

For inline stuff where it's explaining a complex/dense lump of code, it's useful to keep it as close to the original code as possible, so that if somebody updates the code, they're more likely to see/update the comments as well.

j_baker2• 16 years ago

I grant that all code can't be self documenting. But you don't commit suicide just because you're going to die at some point anyway. Instead, you try to make your life as long and happy as possible.

Your highest priority should be to make your code self-documenting as possible, even though that isn't always possible.

That said, the author does have a valid point in that public APIs do need documentation. But I wouldn't go so far as to say that every method (private or not) needs documenting. Unnecessary comments and documentation should be treated like any other kind of useless code. They should be removed.

erikb4• 16 years ago

I think people are too harsh with the author. He is clearly in the beginning of his hacker path. I think everybody who disagrees here can remember a time, when he thought the same way. The author here got a basic idea very correct: You want your code to be readable. And he still has to learn, that good code itself can be (and often is) the most readable way to express a problem and its solution. Often there just is no better way to express, what the coder wants to say.

For everything we code we have to keep in mind that every line we write must have a meaning. That is true for code as much as for documentation. If the problem is complex and the code is hard to grasp, but it is well written, then probably every line of documentation you write will degrade the readability and also end up beeing a waste of the time for its author and its reader.

enneff• 16 years ago

I don't think people are being too harsh. He put his opinions out there in a very proscriptive way. He didn't invite discussion, he merely dictated his opinions. And he is quite wrong.

Additionally, his blog is called ProgFu. That gives the impression that he is highly skilled and experienced; an authority to be heeded, like the sensei of a dojo. But if you look at his writings in total you can see that he's pretty green. His factual pieces are really useful, the opinion pieces less so.

While I'm thinking about it: I'm dismayed by this trend of bloggers dispensing programming advice like they are Miyamoto Musashi himself (although he would never display such hubris). Exchange of information is what's important. If you have a personal experience, share it, and perhaps discuss the lessons you've learned. But, please, don't write articles merely stating your opinions without backing them up with some evidence or experience.

whyme• 16 years ago

  "Almost all programmers type fast, say 400+ characters  
   per minute. So how long does it take to write one two 
   lines of simple text explaining your code? 15 seconds 
   maybe?"

OMG - is this true? He can't be talking about code - can he? I'm lone programmer & self taught. If it's true I must really suck because it takes me so much longer it's not funny. LoL - I have to stop and think, for minutes, almost all the time.

nostrademons• 16 years ago

I don't usually have to stop and think for documentation, though. That's the idea - you're just putting down what's already in your head so that the maintainer can read it.

That said, I usually find that the documentation I write ends up becoming out-of-date about 5 minutes after I write it, because code changes in the process of writing it down. I might write down a docstring to clarify my thoughts, but then the function I actually write doesn't do exactly what I thought it would, and I have to go back and remove or cleanup the docstring later.

bobds• 16 years ago

Programmers who type that fast might not have enough time to think. Typing speed is never the bottleneck.

5teev• 16 years ago

True, one of the most accomplished programmers I know merely hunts and pecks on the keyboard.

rbxbx• 16 years ago

"Code consisting of ShortMethods can reveal the algorithm more directly than procedural code usually does, while hiding the implementation."

http://c2.com/cgi/wiki?ReadingRavioli

Groxx• 16 years ago

  // test 1 + 1 == 2
  function testOnePlusOneEqualsTwo(){
    return (1 + 1) == 2;
  }

I find unnecessary documentation to be unnecessary.

anamax• 16 years ago

How can I make my code explain why it wasn't done some other way, or two other ways?

erikb4• 16 years ago

That is a very good point. But it is not contradicting the main point of most people here. Of course there is good documentation and important documentation. It is just that most of the times your code does not need a big bloat of text around it.

And I would say that your point is a much better example than the one used in the blog post.

mech4bg• 16 years ago

I like Google's viewpoint on this... "incorrect documentation is a bug, and should be fixed." Complaining about the code diverging from the comments therefore comments are worthless is silly imo.

While documentation should not be over the top and code should be readable, I am sick of seeing completely uncommented functions that are non-obvious. There is a happy medium of having easy to read and well styled code and accompanying documentation that explains any gotchas and difficult sections. Sometimes just a written out purpose for the function can be surprisingly useful.

If you've worked in a company with a large shared codebase, you learn to love good comments.

Your Code is Not Self Documenting

Related Stories