I’m not too lazy for comments, but I hate it when the flow of explanation/logic gets piled up with details, all in the same visual style. A source becomes a lenghty book with randomly discussed topics mixed with code. Instead of comments I’d like to emphasize some parts and write irrelevant details and technicalities in a smaller font with a lower contrast. And/or collapse parts of it, but with manual collapse statements, not whereever program syntax allows (I find this completely useless). Also abbreviate expressions into comments that by default replace them completely. E.g.
<cycle through params and start a service for each one>
…
<set up an ocr subprocess and handle errors>
…
if (<is a numeric string>) {
<trim whitespace>
<extract integer part>
<send it to /path/to/route>
}
expands into a corresponding full-page code and more details when you click on these parts. Can’t simulate fonts and colors on HN, sorry. This isn’t exactly literate programming, but more like a programming markdown. I wish it was every language’s way to go. I know you can simulate that with functions and IDE, but having a continuous context has its own benefits (you don’t have to pass it around, which is tedious and again technical), and also naming things properly and in a unique non-polluting way is hard.
I ran into this issue and have settled on very descriptive naming for variables, functions, classes, objects, what have you. I still comment a lot, but it's things you might not infer from the naming conventions. Even when I don't think anybody will ever see the code I do it this way because when I open it up a year later to expand, between the git logs and my comments I'm ready to rock right away.
This is slightly different from my idea. I also comment a lot, create sections of code and use names which at least I can pick up later. My issue is not with names (words), but with a structure of text. A wall of it is “either read or go away”. I’d like to see through it as if it was a high-level description and only dig into details when required. This comes from an observation that you perceive best what’s on the page when you don’t have to jump around and collect knowledge. A page is a best perception unit. Everyone talks about good descriptive names, but then you open any project and see verbAdjNouns at best, which implies that you are familiar with their pretty local jargon.
There are TwoHardThings. I'll take longer descriptive names any day. There is a discussion whether the prefix of words like "get" (i.e. `getName()`) is necessary. Please keep as rare as possible the describing of the _type_ of object, like `MyDataDTO`, `ListOfPeopleArray`, `ApiRequestObject`.
