The Most Important Code Isn't Code • Hacker News Board

Re: The Most Important Code Isn't Code

#21

Post by jacques_chester » Wed, Jun 08, 2011, 12:18 AM UTC

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.

As I understand it, the difference here is that the documentation is actually tested automatically. I believe Python has a tool like this too.

Edit: or maybe not, I can't see mention of it on tomdoc.org. However the format lends itself to that.

For contrast, the D language allows inline tests.

Re: The Most Important Code Isn't Code

#22

Post by bxr » Wed, Jun 08, 2011, 12:19 AM UTC

humbledrone wrote: post #19

bxr wrote: post #18

Earlier quoted context omitted.

I had written a really long response here, drawing on my experience as a software tester. I've deleted my post and have decided to argue my point in another fashion. Please enlighten me to the meaning foo(), here is the documentation: tests = [ #Format: [InputA, InputB, InputC, InputD, Output1, Output2] [1, 2, 3, 4, 12, -7 ], [2, 3, 4, 5, 27, -14], [3, 4, 5, 6, 48, -23], [4, 5, 6, 7, 75, -34], [5, 6, 7, 8, 108, -47],…

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-line function?

Re: The Most Important Code Isn't Code

#23

Post by jacques_chester » Wed, Jun 08, 2011, 12:20 AM UTC

One thing my supervising professor has prodded me to do is to begin keeping a working journal. Nothing fancy, just a plaintext file with date markings.

I've heard the idea before and dismissed it, but it's surprising now how often I will go back and check that journal for why I did something.

I already try to write informative git log entries, but the journal really lends itself to long form exposition.

Re: The Most Important Code Isn't Code

#24

Post by shasta » Wed, Jun 08, 2011, 12:25 AM UTC

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…

Well, comments serve a purpose. For example, if you checked that function into my codebase, I might comment thusly:

    def duplicate_text(text, count):
        """humbledrone, you effing moron, just inline
           the effing astericks"""
        assert False

Re: The Most Important Code Isn't Code

#25

Post by msbarnett » Wed, Jun 08, 2011, 12:25 AM UTC

bxr wrote: post #18

humbledrone wrote: post #4

Earlier quoted context omitted.

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.

I had written a really long response here, drawing on my experience as a software tester. I've deleted my post and have decided to argue my point in another fashion. Please enlighten me to the meaning foo(), here is the documentation: tests = [ #Format: [InputA, InputB, InputC, InputD, Output1, Output2] [1, 2, 3, 4, 12, -7 ], [2, 3, 4, 5, 27, -14], [3, 4, 5, 6, 48, -23], [4, 5, 6, 7, 75, -34], [5, 6, 7, 8, 108, -47],…

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.

And if the hypothetical idiot who wrote your hypothetical test-as-documentation is the same idiot who would instead by providing some other form of written documentation, why would you expect it to be any more clear?

Re: The Most Important Code Isn't Code

#26

Post by abecedarius » Wed, Jun 08, 2011, 12:29 AM UTC

msbarnett wrote: post #16

abecedarius wrote: post #13

Earlier quoted context omitted.

It doesn't communicate the same thing. It communicates one example, leaving the reader to guess how to generalize it. Examples are good, testing is good; and specs are good too. It's currently popular to valorize the first two at the expense of the third, but I think this was an overreaction to the older dogma.

If the general behavior of multiplex isn't clear to the api-user from the example: multiplex('Tom', 4) == 'TomTomTomTom' I'd argue that's a failure of the api designer that no amount of documentation is going to make up for. Examples are good, testing is good, executable, testable documentation is doubly good, and predictable, intuitive api interfaces are invaluable; everything else is a liability that is going to go…

Covering every case provides value that covering just one does not. Natural language communicates in a way code does not. The tradeoffs are a bigger topic than I feel like arguing about in this thread.

(I agree with all you said except the last clause.)

Re: The Most Important Code Isn't Code

#27

Post by bxr » Wed, Jun 08, 2011, 12:41 AM UTC

msbarnett wrote: post #25

bxr wrote: post #18

Earlier quoted context omitted.

I had written a really long response here, drawing on my experience as a software tester. I've deleted my post and have decided to argue my point in another fashion. Please enlighten me to the meaning foo(), here is the documentation: tests = [ #Format: [InputA, InputB, InputC, InputD, Output1, Output2] [1, 2, 3, 4, 12, -7 ], [2, 3, 4, 5, 27, -14], [3, 4, 5, 6, 48, -23], [4, 5, 6, 7, 75, -34], [5, 6, 7, 8, 108, -47],…

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 of that as something that fits the argument/output count)

Re: The Most Important Code Isn't Code

#28

Post by sofuture » Wed, Jun 08, 2011, 12:42 AM UTC

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 absolutely agree. I don't comment all that much, but comment where it's impossible to get clarity -- or comment at a higher level to explain the rationale for the code.

Commenting what code does -- is either 1) pointless or 2) indicative you should rewrite your explanation-requiring code in a more straightforward fashion.

Re: The Most Important Code Isn't Code

#29

Post by wglb » Wed, Jun 08, 2011, 12:55 AM UTC

Ok, I'll be the curmudgeon here.

In recent software development efforts I have run, I have put for the rule that "All comments are bugs". Comments get separated from the code, make statements about obsolete activities, and often mislead the reader, and even sometimes the author.

In place of comments, write code that is as self-explanatory as possible.

I refer to Martin Fowler's "Refactoring" as a way of trying to increase my authority in the matter.

However, I do back off from this extreme position and put comments on individual methods. Sometimes. What helps is using longer method/function/attribute/variable names than pg or tptacek would.

I think the TomDoc example is particularly poorly chosen for the author's thesis, as, more often than not, one is likely to just do "text * num_duplications" inline, no? So why is this even a separate method? Certainly not to save lines of code.

As noted in other comments to this submission, the real value of comments is the why of doing something unusual, not what.

And who was it that said that the Ruby community should spend more time on documentation rather than tools for documentation? A case in point is the doc for EventMachine. This is an insanely useful tool, yet every time I look for the answer to a question about how it operates, the auto-generated documentation leaves me disappointed.

If you are going to spend time on documentation, there is the place to spend it. Make your code readable in its own right.

Re: The Most Important Code Isn't Code

#30

Post by ajg1977 » Wed, Jun 08, 2011, 12:58 AM UTC

The most recent breakthrough in my coding style has been naming methods and variables so that documentation of anything other than input expectations is largely unnecessary.

In your example something like textByRepeatingText(text, times)