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
Search - "self documenting code"
-
A small bug is found.
Chad dev:
😎 *Exists*
> Writes a simple ad hoc solution in a few lines
> Self documenting code with constant run time
> No external dependencies needed
> Fixes the bug, easy to test and does not introduce any new issues
That guy nobody likes (AKA. regex simp coder):
🤡 'This can be "simplified" into oNE LiNe'
> Writes a long regex expression that has to line wrap the editor window several times
> Writes an essay in the comments to explain it's apparent brilliance to the peasant reader
> Exponential run time (bwahahah), excessive memory requirements
> Needs to import additional frameworks, requires more testing that will delay release schedule
> Also fixes bug but the software now needs 2x ram to run and is 3x slower
> Really puts the "simp" in simplified, but not the way you would expect26 -
I have a junior who really drives me up a wall. He's been a junior for a couple of years now (since he started as an intern here).
He always looks for the quickest, cheapest, easiest solution he can possibly think of to all his tickets. Most of it pretty much just involves copy/pasting code that has similar functionality from elsewhere in the application, tweaking some variable names and calling it a day. And I mean, I'm not knocking copy/paste solutions at all, because that's a perfectly valid way of learning certain things, provided that one actually analyzes the code they are cloning, and actually modifies it in a way that solves the problem, and can potentially extend the ability to reuse the original code. This is rarely the case with this guy.
I've tried to gently encourage this person to take their time with things, and really put some thought into design with his solutions instead of rushing to finish; because ultimately all the time he spends on reworks could have been spent on doing it right the first time. Problem is, this guy is very stubborn, and gets very defensive when any sort of insinuation is made that he needs to improve on something. My advice to actually spend time analyzing how an interface was used, or how an extension method can be further extended before trying to brute-force your way through the problem seems to fall on deaf ears.
I always like to include my juniors on my pull requests; even though I pretty much have all final say in what gets merged, I like to encourage not only all devs be given thoughtful, constructive criticism, regardless of "rank" but also give them the opportunity to see how others write code and learn by asking questions, and analyzing why I approached the problem the way I did. It seems like this dev consistently uses this opportunity to get in as many public digs as he can on my work by going for the low-hanging fruit: "whitespace", "add comments, this code isn't self-documenting", and "an if/else here is more readable and consistent with this file than a ternary statement". Like dude, c'mon. Can you at least analyze the logic and see if it's sound? or perhaps offer a better way of doing something, or ask if the way I did something really makes sense?
Mid-Year reviews are due this week; I'm really struggling to find any way to document any sort of progress he's made. Once in a great while, he does surprise me and prove that he's capable of figuring out how something works and manage to use the mechanisms properly to solve a problem. At the very least he's productive (in terms of always working on assigned work). And because of this, he's likely safe from losing his job because the company considers him cheap labor. He is very underpaid, but also very under-qualified.
He's my most problematic junior; worst part is, he only has a job because of me: I wanted to give the benefit of the doubt when my boss asked me if we should extend an offer, as I thought it was only fair to give the opportunity to grow and prove himself like I was given. But I'm also starting to toe the line of being a good mentor by giving opportunities to learn, and falling behind on work because I could have just done it myself in a fraction of the time.
I hate managing people. I miss the days of code + spotify for 10 hours a day then going home.11 -
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.11 -
Code is not self documenting..
reading 10k+ lines of business logic does not take the place of well defined documentation.
Mic drop.28 -
Client dev inlined all my single line functions as it's "more efficient".
Speechless is not the word.14 -
The more someone talks about how code should be "self documenting" the less likely their code is to actually be "self documenting"5
-
Looking through our gitlog today and see 3 PR's from our "lead developer". 2 of these were removing a single blank line from a class, and the 3rd was adding one back in. None of these had any title or commit messages on the PR's. This is a guy that talks down to everyone and deliberately makes other devs feel insignificant, saying he's too busy to write documentation and it's not needed because his uncommented code is self documenting. But hang on he's not too busy to waste time with pointless non-functional PR's that only remove a couple of blank lines? Scratching my head in disbelief that some devs think they can get away with shit like this. How about you drop the ego and actually try and work in collaboration with the other devs.undefined arrogance self documenting code waste of time lead dev no comments pull request bad design2
-
Nothing like writing summary comments on methods to make you feel smart. It's like:
<summary>
ObviousWellNamedMethod is a method that does obvious well named thing
</summary>
<param name="WellNamedObviousParameter">Represents the well named obvious thing used in the obvious well named method</param>
I hate coding standards sometimes.4 -
Architects at the company I'm at rant about, "We don't believe in commenting our code. Good code is self documenting". Nothing about our codebase is "self documenting" FML6
-
Doing and Code Review today... Not sure if this guy has really bad OCD, gets bored, or gets stuck and starts commenting the shit of things...
I'm not sure if I like it or hate it... typically "Good code should be self documenting" but this actually might be acceptable... code on the left, 10K foot view on the right?4 -
OK people, I don't need a novel written for every line of code, but PLEASE STOP trying to tell me that "yOuR coDe sHouLd bE sELf dOcUmeNtiNg aNd cOmMenTs mEaN iT's aUtoMaTiCaLLy bAd". That's a bunch of BS. I can't begin to tell you how many times I've saved my own butt by dropping a "this call can't be awaited; causes the library's internal API to throw an error" comment in my C#, or a "can't use double quotes here; doesn't work right for some reason" line in my JavaScript. Sometimes there are very good but un-obvious reasons why something was done a certain way, even though it looks like it could be done better. And don't try to tell me "the tests will catch it". Let's be realistic here, nobody has 100% test coverage on any project that's much more than "Hello World". And even if the tests DID catch it, why waste the time when you could just write a comment?
P.S.: This is not directed at anyone on here specifically. It's directed at all the devs I've met IRL and the comments I've seen on SO, who think that comments must be bad.12 -
When I'm reviewing code that I'm soon to be working on, I like to add comments to document things that aren't self-documenting.
When I encounter something I have no fucking idea about, I usually add:
// NFI
It's my "safe for work" way to indicate that I literally have no fucking idea what they were attempting.
So I'm curious, does anyone have their own comment "codes" that are safe for commits, but translate into something more awesome?4 -
I need to vent or I'm going to fucking explode like a car filled with bombs in motherfucking Iraq...
A couple of months ago I inherited a project in development from our team leader who was the sole developer on it and he was the one who designed every single thing in it.
I was told the project is clean, follows design patterns, and over all the code is readable and easy.
Those were all fucking lies.
See throughout the period he was working on it, I saw some of the code as it was going through some pull requests. I remember asking the dev why he doesn't comment his code? His response was the most fucking condescending shit I've ever heard: "My code is self-documenting"...
Now that I have full control over the code base I realize that he over engineered the shit out of it. If you can think of a software design pattern, it is fucking there. I'm basically looking at what amounts to a personal space given to that dev to experiment with all kind of shit.
Shit is way too over engineered that I'm not only struggling to understand what the hell is going on or how the data flows from the database to the UI and in reverse, I'm now asked to finish the remaining part and release it in 8 weeks.
Everything is done in the most complicated way possible and with no benefits added at all.
Never in my career have I ever had to drag my sorry ass out of bed to work because I always woke up excited to go to work... well except for the last 2 weeks. This project is now taking a mental toll and is borderline driving me crazy.
Oh, did i tell you that since he was the only dev with no accountability whatsoever, we DO NOT EVEN KNOW WHAT IS LEFT TO BE IMPLEMENTED?
The Project Manager is clueless.. the tickets board is not a source of truth because tickets set to resolved or complete were actually not even close to complete. FUCK THIS SHIT.
For the last week I've been working on 1 single fucking task. JUST 1. The whole code base is a mine field. Everything is done in the most complicated way and it is impossible for me to do anything without either breaking shit ton of other features (Loosely coupled my ass) or getting into fights with all the fucking libraries he decided to use and abuse.
1 whole week and I can't even get the task done. Everyday I have to tell the project manager, face to face, that I'm still struggling with this or that. It's true, but i think the project manager now thinks i am incompetent or just lazy and making excuses.
Maybe I'm not smart enough to understand the what and why behind every decision he made with this code. But I'm sick to my stomach now thinking that I have to deal with this tomorrow again.
I don't know if I'll make the deadline. But I'm really worried that when this is released, I'll be the one maintaining that nightmare of a code base.
From now on, if i hear a fucking developer say their code is "self-documenting" I will shove my dick + a dragon dildo + an entire razor gaming keyboard up their ass while I shoot their fucking knees off.
oh... and there are just a couple of pages of documentation... AND THEY ARE NOT COMPLETE.2 -
At the risk of starting a war, what are folks opinions on in-line comments?
Personally, I'm against them. Self documenting code for the what, SCM for the why.
Comments can get out of date if not maintained; code cannot lie.9 -
Have you ever gotten a task where you have to modify some existing code, and to get it to work the way it needs to you have to write some ugly ass code?
And I'm talking FUGLY ass code. The kind where every brain cell you have screams to refactor it all so that your code won't be so ugly and you can live with yourself. But you only wrote it that way because some numbnuts who was fired a year ago designed it that way, and left zero commentary or documentation on his reasoning ("sELf-dOcUmeNtiNg cOde, bRuH!").
It doesn't pose any sort of risk with regards to security or resource management or efficiency, or really even faulty logic. It just looks fucking awful, my brain can instantly see better ways to design it and I don't want history to tie my name to it.
But also the system is being gutted and retired within a matter of months, so maintenance won't even be a concern; and you know that you have a lot of other large tasks that need your attention too, and to refactor will ultimately prove to be a time sink.
I mean ultimately, I know what I need to do, but I guess it's a pride thing. Just makes me feel icky. -
Stating the obvious when writing comments. 🙈
I used to this when I was starting to learn how to code and let someone read it, 'cause it's better to have comments than nothing, right? 😂 I was wrong.
But that led me to improve writing informative comments and self-documenting codes. -
Debugging a task, that's sending emails to too many customers.
Supervisor: "Never mind, just test in production, there is a dry run flag for the tasks."
Just in case I test locally...
Flags tried:
--dryrun="TRUE" => Error, failed to send mail.
--dryrun=TRUE => Error, failed to send mail.
--dryrun="true" => Not trying to send mail.
If it's THIS PICKY a little more documentation would be nice.
And by a little more I mean: more than the task base class in a giant php monstrosity without phpdocs expecting its code to be self-documenting. -
I'm going to confess: I am the type of developer that creates the ExcruciatinglyLongAndSpecificClassNameObject with the UtterlyDetailedExplanationMethod. It's just a thing I keep doing, despite voiced frustrations from people I've worked with. It just feels right in the mindset of self-documenting code
And while I acknowledge this isn't a flawless process, I see no other way around without losing information. I've tried alternatives, but everything feels like trading one issue for another:
- Abbreviations work as long as they are well known (XML, HTML, ...). As soon as you add your own (even if they make sense in the business context) you can bet your ass someone is going to have no idea what you're talking about. Even remembering your own shit is difficult after X months.
- Removing redundant naming seems fine until it isn't redundant anymore (like when a feature with similar traits gets added). and you can bet your ass no-one is going to refactor the existing part to specify how it differs from the newly added stuff.
- Moving details to namespaces is IMO just moving the problem and pretending it doesn't exist. Also have had folks that just auto-include namespaces in VS without looking if they need the class from namespaceA or namespaceB and then proceed to complain why it doesn't compile.
So, since I am out of ideas, I'd like to ask you folks: Is it possible to reduce class/method name lengths without losing information? Or is self-documenting code just an ideal I'm trying too hard to achieve? Or are long names not a problem at all? I'm looking forward to your answers.19 -
Working on complex invoicing systems. For once, the code is clear, elegant, readable and unit-tested... but I keep forgetting how reality works. If only tax laws were self-documenting.
-
Spent the day refactoring old copy-pasted astronomical code with minimal commentary, cryptic variable names and missing mathematical symbols. Self documenting code my ass.1
-
Coolest project.... SharePoint sucks, so I wrote an app to extend it into something that is useful.
The app consists of:
- a custom SharePoint event receiver to maintain a custom retention setup
- a custom feature to enable users to tag documents as related to each other
- a custom search experience with custom views and previews
- a .Net windows service to sync the data into a SQL database
- a .Net MVC application to manage the reporting and notifications system
- a notifications system in .Net
- custom SharePoint approval workflow
- a PHP site that maintains a full backup of every document in the event that SharePoint goes down
I was the only developer on the entire project and while I asked for backup they never provided it. So if anything happens to me... And since I am a good dev, my code is self documenting and someone will need to telepathically link to me to find out the multiple places that all of this is running (like five different servers including both windows and Linux).
The whole thing, I have about 18 months invested into it ;)