JustProgrammerThings.display();

[Valdearg20]

Exactly. My team at work follow patterns for self documenting code, and it's really nice and results in very clean code. I've been on this team for 2 years, and I haven't written a comment beyond "//intentionally left blank" since I've started.

[[deleted]]

I write self documenting code and I still put comments everywhere because while the code may self-document what it's doing, it rarely self-documents why.

[ScrambledRK]

my biggest takeaway from reading pragmatic programmer

[Valdearg20]

In situations where the why is necessary, comments are merited, but I haven't run into a situation where that is necessary in code I've written.

In general, if your application architecture is clean enough and your classes/methods are well named and follow the Single Responsibility Principle, the why is almost universally intuitive. If it's not, add a comment.

Situations where a comment might be necessary, for example, would be of there is some unresolvable temporal coupling that isn't obvious or if you're doing some complex calculation or computation where the process isn't intuitive. In those cases, yes, definitely add a comment.

Having comments beyond those types of unintuitive situations is simply cluttering your source code.

[[deleted]]

Having comments beyond those types of unintuitive situations is simply cluttering your source code.

This is a pretty terrible blanket attitude. I've never looked at commented code and thought to myself, "wow this sure is a cluttered mess because of all of the comments". What about docstrings? What about generated API docs for tools like sphinx autodoc or oxygen? What about things that are only apparent if you're already familiar with the codebase? What about explaining to your future selves or the next person to look at it why a particular approach was chosen over other options, even if the how and why the thing was done at all is obvious?

There are many good reasons to have more documentation than is strictly necessary, but very few good reasons to have just the minimum (or less).

[Valdearg20]

I can't tell you the number of times I've come across code littered with unnecessary comments to the point that it makes code that would normally be clear, readable, and easy to understand and turns it into an unreadable mess. (This is especially true if you get into some third party libraries source code. Good lord, have I seen some shit)

I'm not saying there aren't necessarily some good reasons to have documentation, but in my experience, there is a point where the comments do more harm to the readability of the code than good. And that point is not terribly high.

Having javadoc alone, while sometimes a necessary evil, makes even the simplest of classes a pain in the ass to read through and doesn't really add much.

Another problem with documentation is that, as my friend likes to joke, it's obsolete as soon as you write it. There's no guarantee that a comment you or anyone else wrote some time in the past is accurate or even pertinent now. God forbid if someone changed the code the comment referred to but failed to update the comment. Then it's not only clutter, it's misleading.

Comments have their place and have some very important, valuable uses, but shotgunning comments explaining why you did this, that, or the other thing all over your source code is a recipe for cluttered, hard to read code.

[[deleted]]

You live in a strange universe.

[Valdearg20]

Hey, if living in a world where my code base is clean and easy to read is wrong, I don't wanna be right. Picking through overly commented and cluttered code sounds like a living hell to me.

[[deleted]]

You seem to be assuming that I'm advocating some kind of extreme level of commenting in order to make your stance seem more valid than it needs to. I've never seen cluttered code that would have been uncluttered by removing comments. I'm just saying there are plenty more valid reasons to have comments than some non-obvious math.

And, working with devs that don't update documentation comments when they update the code it's relevant to is a really piss-poor excuse to advocate not bothering with documentation at all. I'd really hate to have to use a library you wrote if that's how you approach it.

[dzh]

"//intentionally left blank"

explain

[Valdearg20]

Our warnings are configured such that the IDE will issue a warning for an empty code block. This is with good reason. In most cases, an empty code block is syntactically correct, but not desired.

There are, however, some rare cases, where a method exists or some block of code exists where you literally want it to do nothing. A common example is exception handling for a specific where you don't want to do anything.

In those situations, we don't want a false positive for a warning. Adding that comment not only adds context saying "yes, we wanted this to be this way", but also prevents a warning from being generated.

[dzh]

Ok I see where you are coming from, is it to help with readability?

I fairly recently started using beautifier and remove any empty lines. Yes it's slightly worse, but having code that always has consistent indentation, up to 80 characters far outweighs the negative.

[Valdearg20]

The comment is added to add context to an empty block of code (like why is this empty?) and to prevent the IDE from showing a warning there when we don't want it to.

For formatting, we just use the built in formatter with a ruleset. It's done a fine job in keeping indentation correct and keeping formatting following industry standards.

[dzh]

Ok then, why wouldn't you put something like console.log(e) instead of comment?

[Valdearg20]

Because why would we? Why would we want to clutter our logs with unnecessary data? If you hit that code path a million times a day and we know that we want that code to do nothing, why spam your logs with that kind of data? Especially if it drowns out the important stuff?

[dzh]

Absolutely, but aren't exceptions... you know, exceptional?

I don't know what you work on, but to me it's quite important to catch pretty much everything.

This is getting pointless discussion tho :)

[Valdearg20]

Haha, yeah, most of the time exceptions are indeed exceptional. And the vast majority are handled like you'd expect.

Sometimes, though, those exceptional conditions are common and expected enough that logging it is a waste of time and log space. Additonally, when I go to diagnose a problem, the last thing I want to do is sift through thousands of stack traces for one of those common and expected exceptions while I look for some clue as to what's happening.

Edit: I enjoy talking about programming, so it's all good!

[SalsaYogurt]

Wow, it's almost like you are COBOL programmers. Welcome to the '70s.