919
My code is self-documenting (lemmy.world)
submitted 10 months ago by to c/programmer_humor@programming.dev
72 comments fedilink hide all child comments
 
you are viewing a single comment's thread
view the rest of the comments
[–] 121 points 10 months ago (8 children)

A skilled programmer can make self documenting code, so I always document mine.

  • permalink
  • fedilink
  • source
  • hideshow 8 child comments
    •
  • [–] 27 points 10 months ago

    I inherited a code base probably written by a squirrel, and the first thing I did was to write documentation on infrastructure, business logic, architecture, deployment and whatever. I had to read everything anyways, because the guy handing it over had no idea what it did and left the company shortly after. It's fine now, but that path was horrible.

  • permalink
  • fedilink
  • source
  • parent
  • [–] 22 points 10 months ago* (5 children)

    Nah. No code actually documents itself. Ever. Anyone who says they can is an idiot that doesn't understand the purpose of comments and docs.

    Code can never describe intent, context, or consequences unless you read every line of code in every library and framework used, and every external call. Especially if they aren't doing "fail fast" correctly.

  • permalink
  • fedilink
  • source
  • parent
  • hideshow 5 child comments
    •
  • [–] 18 points 10 months ago (4 children) 
    // Prints "Hello World!" to the screen
printf("Hello World!");
  • permalink
  • fedilink
  • source
  • parent
  • hideshow 4 child comments
    •
  • [–] 16 points 10 months ago* (3 children)

    I did not say comments should directly explain what the code is obviously attempting to do.

  • permalink
  • fedilink
  • source
  • parent
  • hideshow 3 child comments
    •
  • [–] 17 points 10 months ago* (2 children)

    My favorite thing about the "all comments are bad" crowd is that their first example is almost always something like this:

    // Add 1 to x
x = x + 1

    Like, nobody that thinks comments are good and important would ever add a useless comment like that. The point of commenting is to add documentation (usually the only form of documentation that a future developer is ever going to read) only to code that would otherwise be inscrutable.

  • permalink
  • fedilink
  • source
  • parent
  • hideshow 2 child comments
    •
  • [–] 6 points 10 months ago* (last edited 10 months ago) (1 child)

    You'd think that, and yet I've once worked in a project in a fortune 500 company that basically wouldn't even compile if we didn't add comments like that. No kidding the compiler enforced specific comment patterns so if you had a line do x = x + 1, it would not compile if it was not preceded by a comment that started with "Add" and included "1" and "to x". Even in dev mode if you wanted to just try something you had to comment everything.

    The original dev was super proud of this tools that generated HTML documentation about everything based on those comments. And the whole documentation was stuff like:

    *price*: The price
  • permalink
  • fedilink
  • source
  • parent
  • hideshow 1 child comment
    •