24
irene
20d

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.

Comments
  • 11
    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.
  • 3
    I used to believe in that sort of shit, thankfully I don't anymore. Now I always write comprehensive comments for any long-term code. I just think to myself "if I had no knowledge of the codebase, would I understand what's going on?", that question generally leads me to writing good documentation.
  • 2
    More people need to see this as truth
  • 2
    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.
  • 3
    @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.
  • 1
    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.
Add Comment