Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Most Important Code Isn't Code

zachholman.com

Post reply on HN
Print view View original

31–40 of 83 posts

Re: The Most Important Code Isn't Code

#31

Post by humbledrone »

bxr wrote: post #22
humbledrone wrote: post #19

Earlier quoted context omitted.

Nope, I am not going to bother. Your function has a terrible name, and the names of the arguments are not available to me. Had you given it a good name, and listed its arguments, I bet that the test would be quite a nice example of how to use it.

But my documentation runs during the hourly and never raises any red flags! That means its right, therefore better than a comment. edit: You did kind of prove my point by asking for documentation outside of the test. If this "documentation" test isn't enough to find out whats really going on in my 1-line function, what makes you think a test and the best-chosen names in the world would give you any insight to a 2-lin…

> But my documentation runs during the hourly and never raises any red flags! That means its right, therefore better than a comment.

Your words, not mine.

Re: The Most Important Code Isn't Code

#32

Post by humbledrone »

bxr wrote: post #27
msbarnett wrote: post #25

Earlier quoted context omitted.

Would any amount of written documentation or comment make foo(a,b,c,d) any less of a hopeless mystery in use? Yes, a poorly written test for a horribly named function with impenetrable argument names make for a shitty experience for the api user, but is that really insightful? Hopelessly meaningless method names with impenetrable arguments would be just as shitty to use if they came with a page-and-a-half of prose. A…

Thats not a documenting test though, thats good choice of names. You don't need tests to have a good choice of names. If I said: slope, yintercept = calculateLine(x1, y2, x2, y2) You wouldn't be using the test as documentation at all. Those names are so goddamn good you don't even need documentation. You would just be using the interface, and basic maths knowledge. (Note: it doesn't actually do that, I just thought o…

That's not a particularly good choice of names, actually:

> slope, yintercept = calculateLine(x1, y2, x2, y2)

It is, in fact, a place where a test would be quite helpful. A test might have prevented the typo for the second argument to calculateLine().

Re: The Most Important Code Isn't Code

#33

Post by [deleted] »

humbledrone wrote: post #31
bxr wrote: post #22

Earlier quoted context omitted.

But my documentation runs during the hourly and never raises any red flags! That means its right, therefore better than a comment. edit: You did kind of prove my point by asking for documentation outside of the test. If this "documentation" test isn't enough to find out whats really going on in my 1-line function, what makes you think a test and the best-chosen names in the world would give you any insight to a 2-lin…

> But my documentation runs during the hourly and never raises any red flags! That means its right, therefore better than a comment. Your words, not mine.

[deleted]

Re: The Most Important Code Isn't Code

#34

Post by bxr »

humbledrone wrote: post #32
bxr wrote: post #27

Earlier quoted context omitted.

Thats not a documenting test though, thats good choice of names. You don't need tests to have a good choice of names. If I said: slope, yintercept = calculateLine(x1, y2, x2, y2) You wouldn't be using the test as documentation at all. Those names are so goddamn good you don't even need documentation. You would just be using the interface, and basic maths knowledge. (Note: it doesn't actually do that, I just thought o…

That's not a particularly good choice of names, actually: > slope, yintercept = calculateLine(x1, y2, x2, y2) It is, in fact, a place where a test would be quite helpful. A test might have prevented the typo for the second argument to calculateLine().

>A test might have prevented the typo for the second argument to calculateLine().

If the compiler didn't puke on it in the definition, or if that was the line in the test it would just be a bug in the test. Of course that all depends on the time honored development tradition of running a hastily written online comment in production. As far as the assumption I'm knocking tests for their utility at testing, I'm not, I'm knocking their utility as documentation.

Re: The Most Important Code Isn't Code

#35

Post by johnl »

humbledrone wrote: post #3

The documentation example for the multiplex() function seems like massive overkill to me. The most informative part of the documentation comment is the line that starts with "Duplicate some text..." So why not just name the function duplicate_text() and be done with it? The arguments could be documented similarly, by naming them "text" and "num_duplications". I don't think I'd need an 11 line comment to tell me what…

For a senior coder, comments may feel redundant but for the junior coder, it helps. If they can't comment the program from beginning to end, they haven't thought the logic through enough to write clean code. And what I like about well written comments, it's easier and faster to either modify or have someone else "step in" with the coding project if necessary, and use to explain to a non-technical manager where you are and what you are doing.

Re: The Most Important Code Isn't Code

#36

Post by msbarnett »

bxr wrote: post #34
humbledrone wrote: post #32

Earlier quoted context omitted.

That's not a particularly good choice of names, actually: > slope, yintercept = calculateLine(x1, y2, x2, y2) It is, in fact, a place where a test would be quite helpful. A test might have prevented the typo for the second argument to calculateLine().

>A test might have prevented the typo for the second argument to calculateLine(). If the compiler didn't puke on it in the definition, or if that was the line in the test it would just be a bug in the test. Of course that all depends on the time honored development tradition of running a hastily written online comment in production. As far as the assumption I'm knocking tests for their utility at testing, I'm not, I'…

> As far as the assumption I'm knocking tests for their utility at testing, I'm not, I'm knocking their utility as documentation.

Except you're not doing that, either. You're knocking the utility of a poorly-written tests-as-documentation test versus the utility of some hypothetically better written documentation.

But if your developers are going to write such uninformative tests-as-documentation, there's no reason to believe their documentation-as-documentation would be any better, so all you're really doing is making the uncontroversial assertion that poorly written documentation sucks.

Making the more relevant and informative comparison of well-written documentation-as-documentation to well-written tests-as-documentation, the tests-as-documentation have the inescapable bonus of being incapable of falling out of sync with the code.

In my, and a lot of other people's, experience, textual documentation tends to become an outdated liability almost as soon as it is written.

Re: The Most Important Code Isn't Code

#37

Post by [deleted] »

bxr wrote: post #22
humbledrone wrote: post #19

Earlier quoted context omitted.

Nope, I am not going to bother. Your function has a terrible name, and the names of the arguments are not available to me. Had you given it a good name, and listed its arguments, I bet that the test would be quite a nice example of how to use it.

But my documentation runs during the hourly and never raises any red flags! That means its right, therefore better than a comment. edit: You did kind of prove my point by asking for documentation outside of the test. If this "documentation" test isn't enough to find out whats really going on in my 1-line function, what makes you think a test and the best-chosen names in the world would give you any insight to a 2-lin…

[deleted]

Re: The Most Important Code Isn't Code

#38

Post by gruseom »

nonzero wrote: post #14
tlrobinson wrote: post #11

Even better than documented code is code that's so clear it doesn't need explanation, with occasional comments explaining the complicated bits. The other case is API docs for libraries and frameworks meant for external consumption.

I actually comment even simple code because comments show up a different color in my editors. Comments for me are often an additional mnemonic trigger rather than necessarily a store of detailed information. It's like indenting or bolding text. It helps with "chunking" while skimming code.

The trouble is that the very same visual cue makes it easy to filter out comments as background noise, so people fail to read them (or even see them) when updating the associated code. As a result, comments don't get maintained and become inaccurate over time. It takes only a small amount of such semantic decay before the comments are a net negative.

Programmers take code seriously. Most don't take comments seriously, even when they believe they ought to. You might say they're bad programmers, but I don't think it's that simple. I think the attention goes straight to code for a reason.

Re: The Most Important Code Isn't Code

#39

Post by roryokane »

Other people have already said most of what I wanted to say – that self-explanatory code, and sometimes tests, is almost always better than comments. I just want to point out a good reference on this topic: the book Clean Code: A Handbook of Agile Software Craftsmanship [1], specifically Chapter 4, “Comments”. That chapter gives examples showing which comments should be turned into code and which are acceptable to leave as comments, and it explains the reasoning behind the choices. (And the rest of the book teaches you how to make your code self-explanatory and easy-to-read.)

[1] http://www.amazon.com/Clean-Code-Handbook-Software-Craftsman...

Re: The Most Important Code Isn't Code

#40

Post by GFischer »

nickolai wrote: post #9
JoeAltmaier wrote: post #8

I can't express how many times I've seen code with comment block boilerplate at the start of every method. And nothing filled in. Its really more common that the other kind. So sure, we all know its great to document. The challenge is figuring out how to get it done. Given that we're all in a hurry, mean well but think we'll get back to it. It feels like you're doing something when you paste in all those blank commen…

>since if it all worked like its commented then there'd be no bugs. Unless it is no longer supposed to work how it was originally written and commented. Software lives and evolves over time. All too often comments go stale. When the Big Bug Day comes, many hours will be wasted on such legacy comments.

At some of the more orderly places I've worked, we put dates on comments.

Also, whenever we made a change, we put a comment (at the top of the class, function, method or whatever is changed), also timestamped, with a reference to the change request ticket (or equivalent), and a summary of the change.

Old comments were deleted if necessary (you could always look them up with a diff on the source control)

Said ticket also had a reference to the code file :) so you had 100% traceability.

The downside being of course it was all very bureaucratic, but there were legal requirements to fill and it was a sensitive, finance sector company. That setup probably wouldn't work for a fast-paced startup :)

Post reply on HN