Coffeehouse Thread

73 posts

The hardest part about programming is...

Back to Forum: Coffeehouse
  • User profile image
    harlock123

    , JoshRoss wrote

     

    *snip*

    For the most part, programmers write poor documentation. Do you think having Microsoft provide a certification for documentation, would improve the situation?

    -Josh

     

     

     

    Have you read some of the MSDN documents?

    No I don't think that would help all that much...

  • User profile image
    Maddus Mattus

    My code documents itself Wink

  • User profile image
    ScanIAm

    , Maddus Mattus wrote

    My code documents itself Wink

    My code obfuscates itself Sad

  • User profile image
    brian.​shapiro

    I document my code, but I also try to create classes that are inuitive representations of the object of what they do...  a lot of the third party libraries I find are really difficult to figure out just because they try to find the cleverest way to do something instead of the most intuitive way to do it.

  • User profile image
    JoshRoss

    , harlock123 wrote

    *snip*

    Have you read some of the MSDN documents?

    No I don't think that would help all that much...

    You hit the nail on the head with that one. I think the problem lies with automatic generated documentation. If it wasn't automatically generated, then I guess someone would have to actually write something about what all these classes are for and what the methods do.

    I wonder if the content would be better if people had to pay for it. Surely, Jaron Lanier would have something to say about that.

    -Josh

     

  • User profile image
    Ion Todirel

    consistency and choises

  • User profile image
    Bass

    Comments are often used as a crutch for sloppy code. Comments can also and often lie, they are ignored by the compiler and thus can say anything no matter how incorrect. Code can not lie. It does what it says.

    Clean code shouldn't need comments. The only time you should use comments is if your code is doing something extremely strange and you couldn't figure out any clean way of doing it.

  • User profile image
    JoshRoss

    @Bass: Sometimes I create ridiculously long method names, and later shorten them, and put in a comment, for the sake of brevity. The stupid thing about that is the simpler the function, the more outrageous the name.

    -Josh

  • User profile image
    Richard.Hein

    @harlock123: Comparitively speaking (to other libraries from other companies), the MSDN docs are pretty good, especially considering how much stuff there is to document. 

  • User profile image
    Richard.Hein

    , Bass wrote

    Comments are often used as a crutch for sloppy code. Comments can also and often lie, they are ignored by the compiler and thus can say anything no matter how incorrect. Code can not lie. It does what it says.

    Clean code shouldn't need comments. The only time you should use comments is if your code is doing something extremely strange and you couldn't figure out any clean way of doing it.

    I'll bet the guy who wrote the 10 year old C++ code I am debugging for memory leaks thought it was obvious what he was thinking, when he wrote it.  Alas, no documentation *at all*.  A whole load of low level memory manipulation to fit into one can only presume was 640K of memory ... <sigh>.

  • User profile image
    DeathBy​VisualStudio

    , Bass wrote

    Comments are often used as a crutch for sloppy code. Comments can also and often lie, they are ignored by the compiler and thus can say anything no matter how incorrect. Code can not lie. It does what it says.

    Clean code shouldn't need comments. The only time you should use comments is if your code is doing something extremely strange and you couldn't figure out any clean way of doing it.

    I've always found people who don't like to comment their code also don't like to test their code and rarely like to use anyone else's code. It's obvious isn't it?

    I guess I don't own an iPhone... Crying

  • User profile image
    davewill

    Programming for the sake of getting something visual for decision makers to wrap their heads around only to find out they like it as is and now we have to support it for 10 years.

  • User profile image
    ScanIAm

    I just finished reading Code Complete and the general practice promoted was to comment

    1) code blocks (maybe.  And if you do, don't just repeat the code, describe what it does.)

    2) methods and parameters

    3) Anything that isn't extremely clear

     

  • User profile image
    kettch

    @ScanIAm:I find it helpful if you comment with more than just the what, but also the why.

  • User profile image
    magicalclick

    @kettch:

    Oh yeah. A lot of times someone comes in and just break it because they didn't know WHY. Althought usually a good Unit Testing can prevent that.

    I usually comment block by block to explain the purpose of each block. So I would know a general implementation flow of a particular method.

    Leaving WM on 5/2018 if no apps, no dedicated billboards where I drive, no Store name.
    Last modified
  • User profile image
    Bass

    , Richard.Hein wrote

    *snip*

    I'll bet the guy who wrote the 10 year old C++ code I am debugging for memory leaks thought it was obvious what he was thinking, when he wrote it.  Alas, no documentation *at all*.  A whole load of low level memory manipulation to fit into one can only presume was 640K of memory ... <sigh>.


    Well you are debugging poorly written code. If the code you are reading is hard to understand, that's the code's problem. I stick to what I said: clean code doesn't need (and shouldn't have) comments. Why? Because clean code is ALWAYS understandable in it's own right.

  • User profile image
    magicalclick

    @Bass:

    Define "Clean Code".

    I did a simple loop of for(int i=1; i<n; i++) and there is an important reason why I do it from 1 instead of 0. No comment will make someone else think it should start from 0. They will change it and break it.

    Leaving WM on 5/2018 if no apps, no dedicated billboards where I drive, no Store name.
    Last modified
  • User profile image
    ScanIAm

    , Bass wrote

    *snip*


    Well you are debugging poorly written code. If the code you are reading is hard to understand, that's the code's problem. I stick to what I said: clean code doesn't need (and shouldn't have) comments. Why? Because clean code is ALWAYS understandable in it's own right.

    Yes.  All one must do is put oneself into the exact mindset of the original coder and enlightenment will occur.  And all projects are of a size that allows a single developer to keep track of all business logic and esoterica within their own head.  And people always interpret names the same way.  And we all speak english.

    Seriously?!?

     

Comments closed

Comments have been closed since this content was published more than 30 days ago, but if you'd like to continue the conversation, please create a new thread in our Forums, or Contact Us and let us know.