20 ms·

Writing maintainable code is a communication skill

297 points by hakunin 5y ago

zuj 5y ago
Haven’t come across this before but I can see myself using this framework of how, what and why in the future. Few thoughts… How: Talking as a mid level programmer, I can’t control the language of choice, I can’t influence the framework or the design. I can control how the individual piece of algorithm is written. What: Apart from the function names, the main important thing here is abstraction. Abstraction is a long term game and it improves with your understanding. The abstraction you choose with a few weeks of exposure to the domain will be entirely different when compared to the person who knows the domain for 10 years. Your abstractions can also changes with the exposure to the actual problem in hand. The more you go down the rabbit hole the more abstraction will keep changing. I like what Kent says here… https://kentcdodds.com/blog/aha-programming https://kentcdodds.com/blog/aha-programming As the author says, it takes years to develop the overall taste but also it takes time to find the right abstraction for solving the problem in the domain. Why: Never thought of comments as the why. I used to think of comments as what more than why. Simple but important distinction. Thanks for the insights.
- zuj 5y ago
  Made a little image to make myself remember this better... https://imgur.com/a/kVXNbsE https://imgur.com/a/kVXNbsE
  - hakunin 5y ago
    Nice, tweeted it crediting this comment: https://twitter.com/hakunin/status/1467223381854539791 https://twitter.com/hakunin/status/1467223381854539791.
    - zuj 5y ago
      That's nice of you. Thanks!
jet_32951 5y ago
There is a parallel to this comment that is not much thought about in mechanical CAD: some designers use tools that get the job done, but the model breaks if you look at it funny. It is all too easy to fall in this trap unless management is willing to pay for models that are maintainable and not just quickly moved out the door. Asking engineers to use the "principle of least astonishment" and develop work others can maintain is difficult at first. It's inculcating the idea of model maintainability and then supporting it against budget constraints that takes the work.
lambdaba 5y ago
In other words, code should be eloquent, it should be as easy as possible to understand why it exists and why the way it is written is correct (or give information as to why the author thought it was correct). Likewise, with regard to modularity, I like the take on codebases that optimize for deletion and not abstraction (after all, abstraction is only a tool, not an objective). These two together make up for the best code IMO.
exabrial 5y ago
The problem is "writing maintainable code" doesn't stroke the ego quite like "writing impressive code"
- zuj 5y ago
  It's programming if "clever" is a compliment, but it's software engineering if "clever" is an accusation. SWE book puts it really well. https://abseil.io/resources/swe-book https://abseil.io/resources/swe-book
wintorez 5y ago
Software development is communication; writing code is a side-activity.
jasonpeacock 5y ago
The challenge is, how do you teach it? Like many writers, many coders think their code is readable and are resistant to feedback. They literally do not see the problem. You can institute all the rules and guidelines you want, but they see it as friction and overhead and only do it because they are forced to.
- klibertp 5y ago
  That's who you need to let go. People resistant to feedback are bad for any role in any company, and if they have their heads so far up their... that they think they know how the code looks for someone else better than that someone else, they really shouldn't have been hired in the first place.
  - deleted 5y ago
    [deleted]
- pydry 5y ago
  The first step is to agree on what it is. I've never actually seen rules or guidelines that were: * Non-trivial - e.g. not about spaces or line lengths or something. * Objective and specific - e.g. with a vague principle like "single responsibility" it doesn't take much to trigger an argument about what constitutes a responsibility. * Actually made it more maintainable - I remember some of the DDD guidelines were non-trivial, objective and specific but they 3-5xed the SLOC. I tried writing some of my own, but it's a lot of work, doesn't generalize very easily and is as likely to spark an argument as it is to actually help.
  - lambdaba 5y ago
    But those are "writing techniques" and not the actual writing / stories. As long as you're having a "conversation" with a codebase by continually reading and editing code you know what parts of the code flow well and are expressive and what parts are not. I think a discussion about the eloquence of a codebase should be had in continuity, parallel to all other individual tasks. Actually the article illustrates some of the criteria like if the code answers "how/what/why" questions. From my own experience the codebases where the code didn't answer those questions were the worst.
daenz 5y ago
>How often have you seen an algorithm expressed with such grace that it appears boringly obvious? There is a perverse quality that I see in mostly junior engineers of not wanting the complicated thing to appear simple. I think it's probably a result of some ego and accomplishment and wanting others to know it was challenging. I'm not sure exactly but I've seen it a lot.
- mistrial9 5y ago
  U know $perl ?
- MeinBlutIstBlau 5y ago
  Where are these juniors graduating from? At my school, asking students to even use python was like asking them to do Microsofts taxes for the year.
- mro_name 5y ago
  there was once a kind of obituary for a super-famous carmaker (Ferdinand Piëch, grandson of Porsche) by a renowned engine-engineer (Friedrich Indra) which boiled down to the fact that "… Piëch was complicated and also explained everything in a complicated way. The art of the engineer is to make things as simple as possible. But if you explain something simply to a person and he understands it immediately, you are just a normal engineer. Someone who exudes this aura of ideas you don't understand, on the other hand, must be something special. …"
  - daenz 5y ago
    It is pessimistic but it resonates. A similar quality I've seen is people who use excessive "lingo" (like obscure abbreviations), when they know that their audience is not as familiar with the subject matter. I find myself constantly stopping them and asking them "what does X mean?" I know I shouldn't feel stupid but I do. I get the sense that it is a similar perspective as that Piech character
sdevonoes 5y ago
I found out that some fellow engineers do not want to write maintainable code, they instead want to write code that: - follows SOLID principles - follows Clean Code principles - follows Hexagonal architecture principles - ... Sometimes such principles do lead to maintainable code, but, most of the time they don't (at least in my limited working experience of around 10 years). An example: If you duplicate code because at the end it seems to be the proper way to write a piece of functionality that will be easier to maintain in the future (and most importantly, it communicates clearly its intention)... well, that's a no-go for some fellow engineers because, somehow, that violates all or some of the principles they have read in some blog post owned by internet celebrities.
- hellectronic 5y ago
  yeah some people think this has to be done. But duplication can be cheaper especially if you are building the wrong abstraction. https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction
- klibertp 5y ago
  Yeah, obsession with DRY to the detriment of readability and maintainability does happen. If you need to write another script like the one you wrote yesterday (but slightly different, and you don't know exactly how different), then starting with a copy&paste is a valid strategy. As you go on you will realize the common points of both scripts, and then you can DRY them both. Or not, if the common parts are too few to bother. Creating complex class hierarchies to "promote reuse" before there even is a case for reuse could be seen as premature optimization or YAGNI. On the flip side, in my experience, people with certain amount of years under their belts tend to treat all those principles in a way they should be, ie. as inspiration instead of as law.
  - __turbobrew__ 5y ago
    A faulty/clumsy abstraction is worse than duplication.
elurg 5y ago
Yes, writing maintainable code requires the ability to explain. There is far far more to "communication skills" than explaining yourself very well, stuff like negotiation and persuasion and conflict resolution. Most of those are less relevant to writing code as much as to getting it accepted.
bloopernova 5y ago
I've found that documentation is one of the first things to go when time-constrained in Sprints. The PM/PO or Team Lead will pay lip service to the idea of allotted time to documentation writing for each Story, but don't enforce that during planning. Nor do they call it out during Retros. Heck, there's some devs, senior and junior, who don't realize the value of standard branch naming, ticket references in commit messages, etc etc. Or they'll pay lip service (again) to a conventions standard, but still continue to work the old way over and over. The common thread among devs that I've spoken to is that they feel they aren't talented enough to write good docs, that they don't have time, and that they don't know what to write about. I feel like the team lead and higher-ups need to focus on enforcing standards for a few sprints to get everyone working on the same page.
tpoacher 5y ago
It's politeness first, and skill second. Most people don't lack skill per se; they just don't give a shit about you.
- drittich 5y ago
  I really don't believe that - it does not match my experience at all. It's just that there are a lot of conflicting forces at play. It's taken my whole career to get better at balancing those forces, and it changes for each scenario. Building software is a people problem, and people (like software) are hard.
- TheCoelacanth 5y ago
  It's often both, unfortunately.
revskill 5y ago
It's about good abstraction. "If a piece of code could be abstracted, it'll eventually be extracted."
agentultra 5y ago
From the opening of Structure and Interpretation of Computer Programs [0] there is the famous aphorism, "Programs are meant to be read by humans and only incidentally for computers to execute." I've been programming for over twenty years. Try as I might to produce code that expresses the problem eloquently and succinctly to unfold the solution in the readers' understanding as they skim through the source... it has rarely ever worked. Firstly you cannot please everyone. And secondly, programs are not structured for pedagogy. Writing maintainable code is a communication skill but I find the best skills are writing, speaking, and illustrating concepts in prose, specifications, white board sessions, chats, etc. The technicalities of ensuring code follows some kind of style guide, design principles, etc plays a big part. But nothing will explain "why" or the big picture stuff quite like a specification or blog post in my experience. [0] https://en.wikipedia.org/wiki/Structure_and_Interpretation_of_Computer_Programs https://en.wikipedia.org/wiki/Structure_and_Interpretation_o... Update: added missing link
- klibertp 5y ago
  I think it is possible to produce code that conveys everything the spec would. The problem is the same as with Donald Knuth literate programming: to use it, you now require your coders to be both great programmers AND great writers. And these two traits rarely coincide in a single person.
  - eikenberry 5y ago
    IMO this is why good developers are so in demand. They are those rare people who are good at both. People who are great at both are the fabled 10X or 100X programmers. Writing code is writing foremost for communication. If you are not good at writing you aren't good at programming. There is really no way around that.
  - entropicdrifter 5y ago
    The other problem with literate programming having been pointed out by McIlroy: https://leancrew.com/all-this/2011/12/more-shell-less-egg/ https://leancrew.com/all-this/2011/12/more-shell-less-egg/
b0rsuk 5y ago
If you have one group of coders writing new functionality, and another doing maintenance work on the application, you have diverging interests. The "new functionality" people have an incentive to rush stuff, because bugfixes won't be their responsibility anyway. The most cynical way to do this is writing a lot of new functionality, put it on CV, and leave for another company.
- kamelionking 5y ago
  A great place to manage your crypto is @coincircle https://coincircle.com/l/2Q_TQamlA5 https://coincircle.com/l/2Q_TQamlA5
FjgdymdjttdjG 5y ago
I interviewed someone from China once who wrote code almost as I write prose. FirstWeCreateAVariableCalledX.AssignItValueY().PassYtoPvalue(); Now imagine 10,000 lines of code written like this and done so in a way that was thoroughly impressive. The creativity alone was startling. I would do it a disservice to further explain. Yes, her object names were ridiculously long, but it was the most readable code ever. It was like she combined the code and documentation together. I'd seen this neither before nor since, and it was strange and beautiful.
chiefalchemist 5y ago
Communication? Maybe. But in my mind it's more of a user experience. That is, someone else picks up your "product" (i.e., code), how easy - or not - is it for them to engage with that product?
kamelionking 5y ago
I just started using @coincircle https://coincircle.com/l/2Q_TQamlA5 https://coincircle.com/l/2Q_TQamlA5
wbsun 5y ago
Sometime it is not the programmers that don't know the benefits of maintainable code or how to write it, it is the culture that rewards short-term velocity instead of long-term reliability. I've seen superstars designing shitty system and writing messy code to workaround processes and policies to launch quickly, and as a reward, they are promoted like taking rockets. It would be really hard for others to not follow the same path as long as the company needs to make money. Long-term benefits are hard to demonstrate while short-term feature/product launches are so obvious.
- peakaboo 5y ago
  I just write simple code and it becomes very maintainable and easy to understand for anyone. In my opinion, it's people who have the need to abstract away everything who complicates the code bases. Give me simple, elegant code that doesn't complicate what the program does, and you have maintainable code that can be changed and deleted easily.
  - hinkley 5y ago
    Used to be, if you didn’t know what else to look for when interviewing people, you’d pick the person who communicated clearly. Because if they’re wrong at least you know quickly, instead of them secretly making a mess for a long time before you figure it out.
  - keyle 5y ago
    I completely agree with this, but this has little to do with the comment you're replying to. Simple dumb code, unless absolutely needed to be "fast and smart", should be the defacto standard. Which is why Go is so good as an enterprise language. Its very design is a standard for maintainability.
  - interactivecode 5y ago
    Everyone always talking about simple code. But what can we agree on that makes code simple?
    - 5y ago
deleted 5y ago
[deleted]
iamwil 5y ago
I usually have the opposite problem. I end up writing clean code because it's the only way I can keep everything in my head, and hence can keep things straight. But it does make me a slower programmer than others, since maintainability takes thoughtfulness, which takes time. That doesn't seem to get rewarded in startups, because often times, your goal is to test the startup hypothesis--and you end up throwing away code anyway. I think only two of my code bases have survived to this day in my whole career. I am convinced that it pays to be faster, since you have more times at bat trying out ideas. I have adjusted and found some ways to eschew clean up because it doesn't matter in the long run, but I'm still struggling to find the right balance after all these years. Anyone out there have heuristics that helps them with this struggle?
- hakunin 5y ago
  Very relatable. Within the context of a single startup this definitely applies. However, in the span of your career, I like to ask — do you want to get fast at writing good code or writing bad code? You won't get perfect code of course, but at the very least you can learn to churn out code that's easy to change. It's not the same thing as expressive code, but it does the job at a startup. (I wrote another article[1] on the topic of writing code that's easy to change a disappointing number of years ago.) [1]: https://max.engineer/cms-trap https://max.engineer/cms-trap
- keyle 5y ago
  It's harder to be correct than to be fast. So I'd keep doing you! However it's hard to say "how slow" you are referring to. If you literally take a day where someone else takes an hour, you might indeed want to work a little faster. One trick I do is I don't get bogged down in details and get it to work fast, even wonky, leaving a trail of "TODO" and "FIXME" comments in the code, that I revisit pre-commit. I want to insist on the fact that I don't want you to commit incomplete or half broken solutions. These have to be attended prior to merging. Some can be so broken that I use "NOCOMMIT" and prevent a commit. The point of this, is that half the time, I saved a lot of time because the solution just wasn't the right way, or the requirement have changed under my feet and I didn't waste any time on those items which would have slowed me down significantly. Also, they're usually tricky things to deal with, and by the end of the feature-complete, I have a much better understand/clarity over the problem, which means solving these TODO and FIXME typically are much easier to deal with, or have become irrelevant/non-issues. Gaining clarity over a problem space is solving half the problem and all of its descendants, and you're far more likely to have that clarity near the end of the feature-complete than 10% into the journey. So my first advice is don't write a specific state postcode validator until much later, when the business is asking you to build the next facebook by tomorrow. I was talking to a friend a few days ago, both of us are quite senior with over 20 years in the industry. He tends to be slower than me and more correct; let's call it pendantic ;) It was quite staggering when we were talking about how things were built, in the metaphore of building a house... I go straight to the foundation and the ground floor, get the walls up as soon as possible, even get a room almost finished to get a good feel for the product. Him, on the other hand, does the drive-way first, polishes the driveway and sets up the mailbox and everything before even looking at the house. Two very different approaches in the form of a metaphore; my argument is, don't waste time on the driveway until you know what the entrance will look like... His argument is, it will need to be done anyway and you can't access the house without a driveway.
abernard1 5y ago
I took issue with this quote > “Isolating complexity in a place where it will never be seen is almost as good as eliminating the complexity entirely.” — John Ousterhout If you can isolate the complexity in one place, it isn't complex. It means that it is definitionally simple and separable. There are things which cannot possibly be isolated and they are complex. Examples are idempotency, things that deal with synchronization or time, resource management across multiple entities. It seems pedantic, but this insight is remarkable in effective system design. If you figure out the inherently complex non-negotiables ahead of time, the rest of your solution becomes pipe-fitting. A large percentage of modern software these days is lost because they start with pipe-fitting and just move the complexity of their problem around endlessly, never identifying it.
joe_the_user 5y ago
My experience has been, the next guy always thinks it's the last guy's fault. But actually the fault usually winds being that of the next guy - even when I was the next guy. Programmers are impatient, we look at the code, the code looks terrible. We lay into with a hatchet and three days later, it works. But there's a very minor problem. You look at the problem, look at it again. Three more days and you've ripped out your code completely, done apologies to the ancestors of the last guy and finally his work and all the problem are solved. And the comment? The communication? No one read them, they made no sense. But once you complete the code, you realize no other comments could have sufficed.
layer8 5y ago
The hardest problem is to adequately foresee the context and the background knowledge future maintainers will have. * Context will change due to modifications and added features in the surrounding code. * One tends to overestimate how much background knowledge a future maintainer will have. * One tends to misjudge which parts of the necessary knowledge will be externally available / still "obvious" in the future.
torresmo 5y ago
I consider maintainability and readability related, but two different things. I'd expect maintainable code to be readable. However, I've encountered code bases that were easy to read, but hard to maintain. I mean that the code was hard to change after new requirements came up. So when writing some code, a programmer needs to have some good understanding on how the business requirements might evolve, and design the code with that in mind, so the next programmer can not only easily read the code, but also change it in face of new requirements.
- hakunin 5y ago
  The problem is that predicting how a business might evolve is pretty much impossible. It might make more sense to architect for ease of change in general rather than ease of change into a specific direction. To do that (aside from the advice in the article), I like to imagine a scale where static/hardcoded/build-time architecture is on the left end, and dynamic runtime-manageable architecture on the right. To avoid over-engineering, the trick is to always lean as much as possible towards the left side of the scale. Only introduce runtime complexity when absolutely needed.

297 points by hakunin 5y ago

zuj 5y ago

Haven’t come across this before but I can see myself using this framework of how, what and why in the future. Few thoughts… How: Talking as a mid level programmer, I can’t control the language of choice, I can’t influence the framework or the design. I can control how the individual piece of algorithm is written. What: Apart from the function names, the main important thing here is abstraction. Abstraction is a long term game and it improves with your understanding. The abstraction you choose with a few weeks of exposure to the domain will be entirely different when compared to the person who knows the domain for 10 years. Your abstractions can also changes with the exposure to the actual problem in hand. The more you go down the rabbit hole the more abstraction will keep changing. I like what Kent says here… https://kentcdodds.com/blog/aha-programming https://kentcdodds.com/blog/aha-programming As the author says, it takes years to develop the overall taste but also it takes time to find the right abstraction for solving the problem in the domain. Why: Never thought of comments as the why. I used to think of comments as what more than why. Simple but important distinction. Thanks for the insights.

zuj 5y ago
Made a little image to make myself remember this better... https://imgur.com/a/kVXNbsE https://imgur.com/a/kVXNbsE
- hakunin 5y ago
  Nice, tweeted it crediting this comment: https://twitter.com/hakunin/status/1467223381854539791 https://twitter.com/hakunin/status/1467223381854539791.
  - zuj 5y ago
    That's nice of you. Thanks!

jet_32951 5y ago

There is a parallel to this comment that is not much thought about in mechanical CAD: some designers use tools that get the job done, but the model breaks if you look at it funny. It is all too easy to fall in this trap unless management is willing to pay for models that are maintainable and not just quickly moved out the door. Asking engineers to use the "principle of least astonishment" and develop work others can maintain is difficult at first. It's inculcating the idea of model maintainability and then supporting it against budget constraints that takes the work.

lambdaba 5y ago

In other words, code should be eloquent, it should be as easy as possible to understand why it exists and why the way it is written is correct (or give information as to why the author thought it was correct). Likewise, with regard to modularity, I like the take on codebases that optimize for deletion and not abstraction (after all, abstraction is only a tool, not an objective). These two together make up for the best code IMO.

exabrial 5y ago

The problem is "writing maintainable code" doesn't stroke the ego quite like "writing impressive code"

zuj 5y ago
It's programming if "clever" is a compliment, but it's software engineering if "clever" is an accusation. SWE book puts it really well. https://abseil.io/resources/swe-book https://abseil.io/resources/swe-book

wintorez 5y ago

Software development is communication; writing code is a side-activity.

jasonpeacock 5y ago

The challenge is, how do you teach it? Like many writers, many coders think their code is readable and are resistant to feedback. They literally do not see the problem. You can institute all the rules and guidelines you want, but they see it as friction and overhead and only do it because they are forced to.

klibertp 5y ago
That's who you need to let go. People resistant to feedback are bad for any role in any company, and if they have their heads so far up their... that they think they know how the code looks for someone else better than that someone else, they really shouldn't have been hired in the first place.
- deleted 5y ago
  [deleted]
pydry 5y ago
The first step is to agree on what it is. I've never actually seen rules or guidelines that were: * Non-trivial - e.g. not about spaces or line lengths or something. * Objective and specific - e.g. with a vague principle like "single responsibility" it doesn't take much to trigger an argument about what constitutes a responsibility. * Actually made it more maintainable - I remember some of the DDD guidelines were non-trivial, objective and specific but they 3-5xed the SLOC. I tried writing some of my own, but it's a lot of work, doesn't generalize very easily and is as likely to spark an argument as it is to actually help.
- lambdaba 5y ago
  But those are "writing techniques" and not the actual writing / stories. As long as you're having a "conversation" with a codebase by continually reading and editing code you know what parts of the code flow well and are expressive and what parts are not. I think a discussion about the eloquence of a codebase should be had in continuity, parallel to all other individual tasks. Actually the article illustrates some of the criteria like if the code answers "how/what/why" questions. From my own experience the codebases where the code didn't answer those questions were the worst.

daenz 5y ago

>How often have you seen an algorithm expressed with such grace that it appears boringly obvious? There is a perverse quality that I see in mostly junior engineers of not wanting the complicated thing to appear simple. I think it's probably a result of some ego and accomplishment and wanting others to know it was challenging. I'm not sure exactly but I've seen it a lot.

mistrial9 5y ago
U know $perl ?
MeinBlutIstBlau 5y ago
Where are these juniors graduating from? At my school, asking students to even use python was like asking them to do Microsofts taxes for the year.
mro_name 5y ago
there was once a kind of obituary for a super-famous carmaker (Ferdinand Piëch, grandson of Porsche) by a renowned engine-engineer (Friedrich Indra) which boiled down to the fact that "… Piëch was complicated and also explained everything in a complicated way. The art of the engineer is to make things as simple as possible. But if you explain something simply to a person and he understands it immediately, you are just a normal engineer. Someone who exudes this aura of ideas you don't understand, on the other hand, must be something special. …"
- daenz 5y ago
  It is pessimistic but it resonates. A similar quality I've seen is people who use excessive "lingo" (like obscure abbreviations), when they know that their audience is not as familiar with the subject matter. I find myself constantly stopping them and asking them "what does X mean?" I know I shouldn't feel stupid but I do. I get the sense that it is a similar perspective as that Piech character

sdevonoes 5y ago

I found out that some fellow engineers do not want to write maintainable code, they instead want to write code that: - follows SOLID principles - follows Clean Code principles - follows Hexagonal architecture principles - ... Sometimes such principles do lead to maintainable code, but, most of the time they don't (at least in my limited working experience of around 10 years). An example: If you duplicate code because at the end it seems to be the proper way to write a piece of functionality that will be easier to maintain in the future (and most importantly, it communicates clearly its intention)... well, that's a no-go for some fellow engineers because, somehow, that violates all or some of the principles they have read in some blog post owned by internet celebrities.

hellectronic 5y ago
yeah some people think this has to be done. But duplication can be cheaper especially if you are building the wrong abstraction. https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction
klibertp 5y ago
Yeah, obsession with DRY to the detriment of readability and maintainability does happen. If you need to write another script like the one you wrote yesterday (but slightly different, and you don't know exactly how different), then starting with a copy&paste is a valid strategy. As you go on you will realize the common points of both scripts, and then you can DRY them both. Or not, if the common parts are too few to bother. Creating complex class hierarchies to "promote reuse" before there even is a case for reuse could be seen as premature optimization or YAGNI. On the flip side, in my experience, people with certain amount of years under their belts tend to treat all those principles in a way they should be, ie. as inspiration instead of as law.
- __turbobrew__ 5y ago
  A faulty/clumsy abstraction is worse than duplication.

elurg 5y ago

Yes, writing maintainable code requires the ability to explain. There is far far more to "communication skills" than explaining yourself very well, stuff like negotiation and persuasion and conflict resolution. Most of those are less relevant to writing code as much as to getting it accepted.

bloopernova 5y ago

I've found that documentation is one of the first things to go when time-constrained in Sprints. The PM/PO or Team Lead will pay lip service to the idea of allotted time to documentation writing for each Story, but don't enforce that during planning. Nor do they call it out during Retros. Heck, there's some devs, senior and junior, who don't realize the value of standard branch naming, ticket references in commit messages, etc etc. Or they'll pay lip service (again) to a conventions standard, but still continue to work the old way over and over. The common thread among devs that I've spoken to is that they feel they aren't talented enough to write good docs, that they don't have time, and that they don't know what to write about. I feel like the team lead and higher-ups need to focus on enforcing standards for a few sprints to get everyone working on the same page.

tpoacher 5y ago

It's politeness first, and skill second. Most people don't lack skill per se; they just don't give a shit about you.

drittich 5y ago
I really don't believe that - it does not match my experience at all. It's just that there are a lot of conflicting forces at play. It's taken my whole career to get better at balancing those forces, and it changes for each scenario. Building software is a people problem, and people (like software) are hard.
TheCoelacanth 5y ago
It's often both, unfortunately.

revskill 5y ago

It's about good abstraction. "If a piece of code could be abstracted, it'll eventually be extracted."

agentultra 5y ago

From the opening of Structure and Interpretation of Computer Programs [0] there is the famous aphorism, "Programs are meant to be read by humans and only incidentally for computers to execute." I've been programming for over twenty years. Try as I might to produce code that expresses the problem eloquently and succinctly to unfold the solution in the readers' understanding as they skim through the source... it has rarely ever worked. Firstly you cannot please everyone. And secondly, programs are not structured for pedagogy. Writing maintainable code is a communication skill but I find the best skills are writing, speaking, and illustrating concepts in prose, specifications, white board sessions, chats, etc. The technicalities of ensuring code follows some kind of style guide, design principles, etc plays a big part. But nothing will explain "why" or the big picture stuff quite like a specification or blog post in my experience. [0] https://en.wikipedia.org/wiki/Structure_and_Interpretation_of_Computer_Programs https://en.wikipedia.org/wiki/Structure_and_Interpretation_o... Update: added missing link

klibertp 5y ago
I think it is possible to produce code that conveys everything the spec would. The problem is the same as with Donald Knuth literate programming: to use it, you now require your coders to be both great programmers AND great writers. And these two traits rarely coincide in a single person.
- eikenberry 5y ago
  IMO this is why good developers are so in demand. They are those rare people who are good at both. People who are great at both are the fabled 10X or 100X programmers. Writing code is writing foremost for communication. If you are not good at writing you aren't good at programming. There is really no way around that.
- entropicdrifter 5y ago
  The other problem with literate programming having been pointed out by McIlroy: https://leancrew.com/all-this/2011/12/more-shell-less-egg/ https://leancrew.com/all-this/2011/12/more-shell-less-egg/

b0rsuk 5y ago

If you have one group of coders writing new functionality, and another doing maintenance work on the application, you have diverging interests. The "new functionality" people have an incentive to rush stuff, because bugfixes won't be their responsibility anyway. The most cynical way to do this is writing a lot of new functionality, put it on CV, and leave for another company.

kamelionking 5y ago
A great place to manage your crypto is @coincircle https://coincircle.com/l/2Q_TQamlA5 https://coincircle.com/l/2Q_TQamlA5

FjgdymdjttdjG 5y ago

I interviewed someone from China once who wrote code almost as I write prose. FirstWeCreateAVariableCalledX.AssignItValueY().PassYtoPvalue(); Now imagine 10,000 lines of code written like this and done so in a way that was thoroughly impressive. The creativity alone was startling. I would do it a disservice to further explain. Yes, her object names were ridiculously long, but it was the most readable code ever. It was like she combined the code and documentation together. I'd seen this neither before nor since, and it was strange and beautiful.

chiefalchemist 5y ago

Communication? Maybe. But in my mind it's more of a user experience. That is, someone else picks up your "product" (i.e., code), how easy - or not - is it for them to engage with that product?

kamelionking 5y ago

I just started using @coincircle https://coincircle.com/l/2Q_TQamlA5 https://coincircle.com/l/2Q_TQamlA5

wbsun 5y ago

Sometime it is not the programmers that don't know the benefits of maintainable code or how to write it, it is the culture that rewards short-term velocity instead of long-term reliability. I've seen superstars designing shitty system and writing messy code to workaround processes and policies to launch quickly, and as a reward, they are promoted like taking rockets. It would be really hard for others to not follow the same path as long as the company needs to make money. Long-term benefits are hard to demonstrate while short-term feature/product launches are so obvious.

peakaboo 5y ago
I just write simple code and it becomes very maintainable and easy to understand for anyone. In my opinion, it's people who have the need to abstract away everything who complicates the code bases. Give me simple, elegant code that doesn't complicate what the program does, and you have maintainable code that can be changed and deleted easily.
- hinkley 5y ago
  Used to be, if you didn’t know what else to look for when interviewing people, you’d pick the person who communicated clearly. Because if they’re wrong at least you know quickly, instead of them secretly making a mess for a long time before you figure it out.
- keyle 5y ago
  I completely agree with this, but this has little to do with the comment you're replying to. Simple dumb code, unless absolutely needed to be "fast and smart", should be the defacto standard. Which is why Go is so good as an enterprise language. Its very design is a standard for maintainability.
- interactivecode 5y ago
  Everyone always talking about simple code. But what can we agree on that makes code simple?
  - 5y ago

deleted 5y ago

[deleted]

iamwil 5y ago

I usually have the opposite problem. I end up writing clean code because it's the only way I can keep everything in my head, and hence can keep things straight. But it does make me a slower programmer than others, since maintainability takes thoughtfulness, which takes time. That doesn't seem to get rewarded in startups, because often times, your goal is to test the startup hypothesis--and you end up throwing away code anyway. I think only two of my code bases have survived to this day in my whole career. I am convinced that it pays to be faster, since you have more times at bat trying out ideas. I have adjusted and found some ways to eschew clean up because it doesn't matter in the long run, but I'm still struggling to find the right balance after all these years. Anyone out there have heuristics that helps them with this struggle?

hakunin 5y ago
Very relatable. Within the context of a single startup this definitely applies. However, in the span of your career, I like to ask — do you want to get fast at writing good code or writing bad code? You won't get perfect code of course, but at the very least you can learn to churn out code that's easy to change. It's not the same thing as expressive code, but it does the job at a startup. (I wrote another article[1] on the topic of writing code that's easy to change a disappointing number of years ago.) [1]: https://max.engineer/cms-trap https://max.engineer/cms-trap
keyle 5y ago
It's harder to be correct than to be fast. So I'd keep doing you! However it's hard to say "how slow" you are referring to. If you literally take a day where someone else takes an hour, you might indeed want to work a little faster. One trick I do is I don't get bogged down in details and get it to work fast, even wonky, leaving a trail of "TODO" and "FIXME" comments in the code, that I revisit pre-commit. I want to insist on the fact that I don't want you to commit incomplete or half broken solutions. These have to be attended prior to merging. Some can be so broken that I use "NOCOMMIT" and prevent a commit. The point of this, is that half the time, I saved a lot of time because the solution just wasn't the right way, or the requirement have changed under my feet and I didn't waste any time on those items which would have slowed me down significantly. Also, they're usually tricky things to deal with, and by the end of the feature-complete, I have a much better understand/clarity over the problem, which means solving these TODO and FIXME typically are much easier to deal with, or have become irrelevant/non-issues. Gaining clarity over a problem space is solving half the problem and all of its descendants, and you're far more likely to have that clarity near the end of the feature-complete than 10% into the journey. So my first advice is don't write a specific state postcode validator until much later, when the business is asking you to build the next facebook by tomorrow. I was talking to a friend a few days ago, both of us are quite senior with over 20 years in the industry. He tends to be slower than me and more correct; let's call it pendantic ;) It was quite staggering when we were talking about how things were built, in the metaphore of building a house... I go straight to the foundation and the ground floor, get the walls up as soon as possible, even get a room almost finished to get a good feel for the product. Him, on the other hand, does the drive-way first, polishes the driveway and sets up the mailbox and everything before even looking at the house. Two very different approaches in the form of a metaphore; my argument is, don't waste time on the driveway until you know what the entrance will look like... His argument is, it will need to be done anyway and you can't access the house without a driveway.

abernard1 5y ago

I took issue with this quote > “Isolating complexity in a place where it will never be seen is almost as good as eliminating the complexity entirely.” — John Ousterhout If you can isolate the complexity in one place, it isn't complex. It means that it is definitionally simple and separable. There are things which cannot possibly be isolated and they are complex. Examples are idempotency, things that deal with synchronization or time, resource management across multiple entities. It seems pedantic, but this insight is remarkable in effective system design. If you figure out the inherently complex non-negotiables ahead of time, the rest of your solution becomes pipe-fitting. A large percentage of modern software these days is lost because they start with pipe-fitting and just move the complexity of their problem around endlessly, never identifying it.

joe_the_user 5y ago

My experience has been, the next guy always thinks it's the last guy's fault. But actually the fault usually winds being that of the next guy - even when I was the next guy. Programmers are impatient, we look at the code, the code looks terrible. We lay into with a hatchet and three days later, it works. But there's a very minor problem. You look at the problem, look at it again. Three more days and you've ripped out your code completely, done apologies to the ancestors of the last guy and finally his work and all the problem are solved. And the comment? The communication? No one read them, they made no sense. But once you complete the code, you realize no other comments could have sufficed.

layer8 5y ago

The hardest problem is to adequately foresee the context and the background knowledge future maintainers will have. * Context will change due to modifications and added features in the surrounding code. * One tends to overestimate how much background knowledge a future maintainer will have. * One tends to misjudge which parts of the necessary knowledge will be externally available / still "obvious" in the future.

torresmo 5y ago

I consider maintainability and readability related, but two different things. I'd expect maintainable code to be readable. However, I've encountered code bases that were easy to read, but hard to maintain. I mean that the code was hard to change after new requirements came up. So when writing some code, a programmer needs to have some good understanding on how the business requirements might evolve, and design the code with that in mind, so the next programmer can not only easily read the code, but also change it in face of new requirements.

hakunin 5y ago
The problem is that predicting how a business might evolve is pretty much impossible. It might make more sense to architect for ease of change in general rather than ease of change into a specific direction. To do that (aside from the advice in the article), I like to imagine a scale where static/hardcoded/build-time architecture is on the left end, and dynamic runtime-manageable architecture on the right. To avoid over-engineering, the trick is to always lean as much as possible towards the left side of the scale. Only introduce runtime complexity when absolutely needed.