Coffeehouse Thread

10 posts

Forum Read Only

This forum has been made read only by the site admins. No new threads or comments can be added.

don't know if any of you are on dzone

Back to Forum: Coffeehouse
  • User profile image
    SaraJoRedux

    but can you vote my blag entry up? I really think I'm sharing something important, do you agree? if you disagree feel free to trash it. 

    http://www.dzone.com/links/documentation_a_sure_sign_of_garbage_code.html



  • User profile image
    Bas

    While I wouldn't agree that all code should be devoid of comments, I agree with the general sentiment. Documenting your code is essential, but I think you should always attempt to make your code as self-documenting as possible so you don't need comments anymore.

    How is that done? With clear, verbose function/variable names and a bunch of disciplines like making sure a function only does one thing, and does it well. If you have a function called "WriteData" that writes stuff to a file and clears a buffer, you're doing it wrong. Chop those babies up into a function called WriteFile() that writes a file, and a function called ClearBuffer() that clears a buffer. Clear function names that do exactly what they say, and no extra functionality that you need documentation for to know about them. You could call these functions one after the other in a separate function on a higher level of abstraction, that has a more application specific name.

    One commenter on your blog said

    Not every user of your code can see the internals of it (i.e. may only be able to see the method signiture, not the implementation). This is most nessicary when your code is becoming part of a library that doesnt have source attached.


    The whole point of abstraction is that people don't need to see the internals of your code. Somebody using a class library has no business poking around in that library's code. All you need is the public interface. So make sure that public interface has clear names that convey exactly what the classes are for and what their methods do.

    (Sidenote: I use XML comments so that Visual Studio gives nice tooltips and I can generate some documentation. It's more of a finishing-touch type thing than an actual necessity, although I do find class libraries that don't provide short, sweet tooltip descriptions kind of amateurish. Although that's usually because the naming is so unclear that I need to look at the tooltip.)

    And hey, I don't have a dzone account, so I can't upvote. Sorry.

  • User profile image
    Sven Groot

    I disagree wholeheartedly.

    A few years back I had to work on an existing tool developed by some other students at Leiden University. And I can do nothing but compliment their style. Their code was clear, easy to read. The design was fantastic. The naming was spot on. They had unit tests for everything.

    Except for one thing: there were no comments. Zero. Nada. Nilch.

    And it was impossible to get a grip on the code. I had to spend half a day with one of the original developers so he could walk me through how all the pieces fit.

    The bottom line: no matter how great your code is, any project of sufficient size will need documentation. Otherwise it's just not possible to see how the pieces fit together.

    Of course, I strongly discourage comments like this:
    // increment by n;
    x += n;

    Don't comment the obvious. But please, document the structure of the code.

  • User profile image
    Minh

    Sven Groot said:
    I disagree wholeheartedly.

    A few years back I had to work on an existing tool developed by some other students at Leiden University. And I can do nothing but compliment their style. Their code was clear, easy to read. The design was fantastic. The naming was spot on. They had unit tests for everything.

    Except for one thing: there were no comments. Zero. Nada. Nilch.

    And it was impossible to get a grip on the code. I had to spend half a day with one of the original developers so he could walk me through how all the pieces fit.

    The bottom line: no matter how great your code is, any project of sufficient size will need documentation. Otherwise it's just not possible to see how the pieces fit together.

    Of course, I strongly discourage comments like this:
    // increment by n;
    x += n;

    Don't comment the obvious. But please, document the structure of the code.
    I agree with Sven (that comments are good) in theory, but fail miserably in practice.

    I wonder where I really fall in this debate.

    *in need of some soul searching*

  • User profile image
    Maddus Mattus

    Just wait when you see that line of code and you go; what the hell is this for?

  • User profile image
    SaraJoRedux

    Maddus Mattus said:
    Just wait when you see that line of code and you go; what the hell is this for?
    I feel like no one is really reading my article.


    When you do something that goes against common coding practice you should def comment that.

  • User profile image
    Maddus Mattus

    SaraJoRedux said:
    Maddus Mattus said:
    *snip*
    I feel like no one is really reading my article.


    When you do something that goes against common coding practice you should def comment that.
    What's my point? Stop documenting code!


    I read ya Smiley

    I just dont agree. Just because you hate do it and to read it, doenst mean it sux.

    I highly value inline comments. I highly value lengthy descriptions. Then I dont have to read a gazillion pages of documentation.

  • User profile image
    AndyC

    SaraJoRedux said:
    Maddus Mattus said:
    *snip*
    I feel like no one is really reading my article.


    When you do something that goes against common coding practice you should def comment that.
    Bad comments are worse than no comments which is worse than good comments. The examples you cite in your post are most definitely bad comments, but I wouldn't go so far as to recommend no comments at all. There is a skill in putting in the right comments to enhance the readability of the code.

  • User profile image
    Royal​Schrubber

    Argh, this is precisely why I hate blogs. You fit stereotype about bloggers perfectly - stop wasting time with posting random nonsense on the internets. Millions of developers are doing it, which is enough evidence  that should stop you before you even start thinking about writing such articles.


    In blog:

    So, basically, writing manual for your code basically says that there is the chance the person reading it may not understand what they are looking at.
    Why even save source when you can give binaries to developers coming to project after you. Because everyone should know assembler and those who can't read raw x86 opcodes in hexeditor are just retards right?
    Instead of reading nice documentation you'd rather spend 10x as much time trying to understand what a blob of comment-less code does. Maybe you're smart and you could get away with smaller project, but not with multi-thousand lines long project. 

    Nah, your omniscient genius doesn't need no stupid comments... I assume you know C - then download Linux kernel, let's see how far you can go without documentation..

    Perplexed

  • User profile image
    Bas

    RoyalSchrubber said:
    Argh, this is precisely why I hate blogs. You fit stereotype about bloggers perfectly - stop wasting time with posting random nonsense on the internets. Millions of developers are doing it, which is enough evidence  that should stop you before you even start thinking about writing such articles.


    In blog:
    So, basically, writing manual for your code basically says that there is the chance the person reading it may not understand what they are looking at.
    Why even save source when you can give binaries to developers coming to project after you. Because everyone should know assembler and those who can't read raw x86 opcodes in hexeditor are just retards right?
    Instead of reading nice documentation you'd rather spend 10x as much time trying to understand what a blob of comment-less code does. Maybe you're smart and you could get away with smaller project, but not with multi-thousand lines long project. 

    Nah, your omniscient genius doesn't need no stupid comments... I assume you know C - then download Linux kernel, let's see how far you can go without documentation..

    Perplexed
    I assume you know C - then download Linux kernel, let's see how far you can go without documentation..


    From what I've seen of the Linux kernel, it was hardly verbose, readable code with well named functions and variables either. So not being able to get anywhere with no documentation is no real surprise in that case.

Conversation locked

This conversation has been locked by the site admins. No new comments can be made.