

Your Code is Not Self Documenting - darthdeus
http://progfu.com/post/2668280164/your-code-is-not-self-documenting

======
wccrawford
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.

~~~
erikb
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.

~~~
lelele
> 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.

~~~
erikb
Your conclusions are soooo right. Really. It is exactly the same thing as
tidyness in your room.

Where does this tidyness come from? It doesn't come from often cleaning up the
shit you made, hopefully before it hits any fans. For most people it comes
from having an order of things in your shelves and teaching yourself to not
drop everything you hold in your hand just where you don't need it anymore,
but put it back in the place where it belongs.

My argument is that - and that is where I can be right or wrong - you write
good or bad code because you have the skill to do so. And also that you write
good or bad code because you have an order for things and a (somewhat
engineeringly/scientifical) process of writing code, that the readability in
your code does not come from saying "I make it clean now" but from the sum of
all the small steps that produce the least amount of shit as a sideeffect.

The thing is, if you have ugly code that is not easy to understand, the author
didn't really understand the problem and the solution either. It was more the
magician approach, where you put in many things together and suddenly it works
approxamitally how the author has planned (probably there are also no good
designed structure documents and unit tests in such a case). And then he just
said "okay, now it's finished." If you come and "refactor" it, it is actually
that YOU will be the one who solves the real problem the first(!) time,
because the ugly code obviously doesn't solve any problem well enough
(otherwise, where does the bug reports come from that are so hard to solve).

Okay, that is that. But from your argument, lelele, I wonder, if my secon
point was also unclear. I meant that you should of course handle the mess, but
WHEN IT IS ABSOLUTELY NESSESARY. If you don't need to, if you can live with
the mess in this moment right now and if the problems (bugs etc.) are not that
bad (e.g. don't need to be fixed at the moment, because there are bigger
things to do), then don't solve the problem NOW. BUT ALSO when the time comes
and you have a bug, that really needs to be fixed you should take the time and
energy and really clean up the code first. In my small experience (2 years are
not enough to be really sure yet) a good process is the following:

1\. you discover a problem (through bug reports, dying servers, a screaming
boss running your way, you-name-it)

2\. you define and evaluate the problem (Is it a problem? Do I(!) need to
solve it? Is it worth the time I will spent on it? etc.)

3\. you write unit tests to keep the actual thing that the program does
without changes and find the place in the code where the bug occurs.

4\. now that you can not destroy functionality you plan how to change the
system that it is more clean. (cleaning up the smallest amount of code
possible)

5\. after cleaning up your code your problem either is already solved (happens
often in my experience) or gets some fixing now (done by you of course).

With this process you reach many goals at once and make sure to not put in
resources that are not nessesarily needed. Also you can see that this process
is able to handle ugly code, situations where unit tests where forgotton to
write and basically many kinds of mistakes that coders do because they are
humans (error prone and lazy).

By the way, the same process also works for new feature requests.

------
j_baker
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.

------
Jach
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
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.

------
erikb
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
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

      "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.

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

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

------
mech4bg
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.

------
rbxbx
"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>

------
ShardPhoenix
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.

~~~
rnemo
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.

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

~~~
erikb
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.

------
sliverstorm
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.

------
Groxx

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

I find unnecessary documentation to be unnecessary.

