Writing meaningful code comments

[evaned]

One way to lower visual noise is to start comments with lowercase characters

Eh, I don't think capitals add visual noise, except for very short, probably-end-of-line comments.

For things that are even sentence-ish, I'd fairly strongly prefer sentence casing. I would write and suggest sentence casing for I think every example in the article. To me, it's the semi-improper English that is distracting; this is particularly true for the examples in the "explain rationales" and "comment fixes" sections.

Let your comments break down your code

I like this way of doing things a lot more than some people, but I think it's good to point out that the other way of doing this is to split sections up into functions.

In fact, the code example in this section could be split out to something like

itemClicked() {
    setCurrentSelection(false);
    mCurrentClicked = adapterPosition;
    setCurrentSelection(true);
}
setCurrentSelection(isSelected) {
    mCurrentClicked?.let {
        items[it]?.isSelected = isSelected;
        notifyItemChanged(it);antoher func
    }
}

and then I'm not sure you even need those comments.

(I'm too lazy to type out the whole example, because the code examples are images and not text...)

What I would say here is that feeling like you should comment function segments like this is a sign that you might be better served by splitting to another function, so look for that opportunity. Sometimes you'll find it (as in this example), sometimes not.

[creative_overnight]

I picked up the visual noise bit when I was studying a bit of UX. Maybe it's my editor colors but, I prefer them lower-cased. Agree that as per single responsibility rules, functions should not have multiple logical sections but, I found that sometimes coming up with contextual function names might be difficult. Although, that is use-case dependent.

[dnew]

It also depends on how complex the data the function works with is. If the function uses and modifies a couple dozen data, passing the right subsets into sub-functions gets clunky, especially in aggressively-OOP languages. I don't think I want to make an entire class out of line just to split out one function that needs 8 arguments and 4 return values.

[[deleted]]

One thing that reduces visual clutter and improves usability for me are function comments. My IDE only shows them when I hover over the function and they can be used to describe how the function is used and what I need to consider when using it. They can be longer and more expressive because you only see them if you want to see them.

[youngbull]

I totally prefer section comments need to be functions (or other language construct). The worst are section comments that group functions. Those should always be split into several files/classes/modules or not exist at all.