Join devRant
Do all the things like
++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatar
Sign Up
Pipeless API
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple API
Learn More
-
i don't think optimized code and "self-documenting" code can coexist. If it's optimized, it's usually condensed and using many funcs and such to do its job, making it way less readable, which is the opposite of "self-documenting" code. Even something as dead-simple as a long list of "if/elif/else: <basic math operation>" can be confusing as fuck if it's condensed to shit (unrelated note: case statements when, python?) Comments are always still needed. Code that can explain itself is possible and all, but that usually only explains immediates and not the larger part or the whole.
-
Currently working in a codebase with practically no comments. Slowly figuring out what things do, but some things are still unknown. I try to comment on really significant things, especially outright hacks. I also try to use very descriptive variable names, but I am not sure that is enough. I may have to relearn the code I am writing.
-
@Demolishun in my case the worst part is how little the application actually does. People spent so much time being clever. After I joined the team they were all annoyed at the way I coded and griped about how I added comments. I’m one file I destructured about 300 lines of overly complex clever looking shitcode and replaced them with 50 readable lines which passed all the tests.
Now at least they are coming around to the realization that pretty shitcode is not actually contributing to codebase order. Nobody understands it so nobody can refactor it or maintain it. So people slap a comment-free shitcode procedure to the end of the other shitcode to correct it. Does it look clever and clean? You bet. Is it? Not at all. -
Selfdocumenting code is possible. But:
It only documents, what it actually does.
It doesn't tell, why it is needed to do what it does.
It also doesn't tell anything about the bigger picture outside its execution context.
So selfdocumenting code doesn't mean code without any comments. It also doesn't mean architecture without documentation.
It just means that the code itself doesn't need any comments to tell the casual reader what it actually does for any possible input.
And also it is hard to write self-documenting code, but it is even harder to write good comments for non-self-documenting code and keep that in sync with the actual code whenever that is altered. -
Self documenting code exists. With good naming, small methods and good structure it's easy to read and understand. But in some places it's nearly impossible to write self documenting code because of some optimizations or forced workarounds. In this case developers should write comments describing what they are doing and why they are doing. Otherwise it will be harder to figure out what's going on.
-
@Gxost those things explain what is happening but not why they are happening.
-
@irene Class name should be self-descriptive. If it's hard to create a good self-descriptive name documenting comments can be used. But if you need description why something is happening than there should be some article describing software architecture. Comments document some part of code but not why parts of code are used.
-
@Gxost Last week I came upon an area of code where certain specific kinds of values were filtered out before being returned. I looked in git history and I went back several years and only found squashed commits that didn’t address the logic. Once was a white space change. I looked in confluence and it was impossible to find anything. I looked at the linked jira ticket and no mention of the filtering.
So I called up the dev and asked. He told me “the line was there because the system would break with the old auth system.” The line was so that they could release the code on time and the problem was solved immediately after the release.
How about a fucking comment? This comment could have saved me four hours.
// patch: The exception will be addressed after the 2.6 release when the authentication is updated.
The only thing this documented was how retarded it is to avoid comments because of ideology instead of choosing pragmatism.
when your code is a mess but everything work out in the end
When you keep getting +1s on a rant you posted a month ago.
Go big or go home.
Self documenting code is a fucking myth you bloody sheep.
Write “self documenting code” then add a fucking comment or two explaining why the fuck the code deserves should be there because nobody can see what the fuck it is doing or understands how the whole collection of microservices works. I’m sick of spaghetti code bullshit full of accidental redundancy because it is impossible for anyone to realize why something is there at a glance.
I renamed different “Contract” classes today by adding numbers before code review.
Contract
Contract1
Contract2
Contract3
All of these classes are supposed to be the same but somehow they aren’t and you self documenting dumbasses missed it. Don’t gripe about the numbered classes in the repo… fix the fucking code and collapse the classes so we don’t have four sections of code describing the same fucking structure from a http get with different interfaces because four people couldn’t read the whole like some fucking computer.
rant
self documenting code