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

1–10 of 83 posts

Re: The Most Important Code Isn't Code

#3

Post by humbledrone »

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 this definition did:

  def duplicate_text( text, num_duplications )
    text * num_duplications
  end
In fact, I might prefer NO comment, because comments can become out of date and misleading, whereas the code always tells the truth.

Re: The Most Important Code Isn't Code

#4

Post by humbledrone »

kenneth_reitz wrote: post #2

I couldn't agree more. Writing documentation tells me more about my own code than any level of testing ever has. Both are important of course. ;)

You mean to say that a test like the following wouldn't be better than the comment for multiplex()?

  unless multiplex('Tom', 4) == 'TomTomTomTom'
    raise TestError( 'multiplex() failed' )
  end
Not only does that test communicate the exact same thing as the documentation comment, it is guaranteed to be correct and not out-of-date (assuming it's run as part of a test suite), whereas the comment can easily be wrong.

Re: The Most Important Code Isn't Code

#5

Post by holman »

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…

That was pulled from the TomDoc spec- it was designed to demonstrate TomDoc, not the code. Having an overly complicated implementation makes explaining the documentation side of things a bit more difficult. :)

Re: The Most Important Code Isn't Code

#6

Post by waratuman »

Good documentation is great, but its importance grows with the size of the project. It isn't as important in a Rails app where only a few people touch the code and the concepts already well known about the framework.

The project can grow both in terms of code size and the number of people engaged. Each drives up the importance of documentation.

Re: The Most Important Code Isn't Code

#7

Post by humbledrone »

holman wrote: post #5
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…

That was pulled from the TomDoc spec- it was designed to demonstrate TomDoc, not the code. Having an overly complicated implementation makes explaining the documentation side of things a bit more difficult. :)

Ah, I see, it's an example of how to, not when to. :)

Re: The Most Important Code Isn't Code

#8

Post by JoeAltmaier »

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 comment blocks. But soon you don't even see them, since first off they're usually blank, and second when debugging you're looking for the code not the comments, since if it all worked like its commented then there'd be no bugs.

Re: The Most Important Code Isn't Code

#9

Post by nickolai »

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.

Re: The Most Important Code Isn't Code

#10

Post by sparky »

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…

Not to mention the fact that the word "multiplex" already has a meaning, and it has nothing to do with concatenating duplicates of a string. Unless the function name is intended to be parsed as "multiple 'X'".
Post reply on HN