DEV Community

The best software engineers write instead of code

Shailen Naidoo on February 18, 2024

There is this misconception that software engineering comprises of several people getting together and writing code to meet an end goal but that is...
Collapse
 
thumbone profile image
Bernd Wechner • Edited

Reminds me of a quip of mine that I posted on rec.humor.funnny in the '80s. There was a run of "a good something does this and a bad something that" style of aphorism being posted to take the mickey out of something out other.

My contribution after having worked on extensive refractors of old black box code systems no-one would touch because they didn't know how they worked running mission critical 24/7 operations. I laced the refractors with more lines of commentary than there was code too ensure any noob picking this up know exactly what's going on where and why and weren't scared of maintaining it and bringing it forward with the times.

It was clear already then that the cost maintenance way outstripped the the cost of initial development over time and that one of the central reasons was black box coding, the culture of prioritising code over commentary of building what solutions with no succession planning etc.

So in the culture of rec.humor.funny, I quipped on that newsgroup (using nn with by Kim Storm which I contributed some code to for HP-UX terminal support) - paraphrased as memory does not retain literal accuracy over 4 decades:

The bad programmer writes code in C for the computer and documents it in English for their peers. The good programmer writes code in English for their peers and documents it in C for the computer.

It made it into print in one of the rec.humor. funny anthologies from memory.

Collapse
 
shailennaidoo profile image
Shailen Naidoo

Thanks for sharing this, it must be a great memory to have. I often say to people now that code is not important, what is more important is the documents that you are leaving for the next person.

Collapse
 
olierxleben profile image
Oliver Erxleben

I often use a whiteboard or some tools like obsidian to write down the solution or making low level diagrams of the data flow or how information will be transported from / to the user.

Helps me understanding the whole user journey.

Collapse
 
igorrubinovich profile image
Igor Rubinovich

Also diagraming tools like draw.io or mermaid.live (or a vscode mermaid plugin for that matter)

Collapse
 
bigboybamo profile image
Olabamiji Oyetubo

+1 for Obsidian. Been using it for 2 years now

Collapse
 
shinyvision profile image
Rachel Snijders

I don't do this. I don't start jotting down code immediately either. In my case, the iterative process of building concise parts of a software product lends itself extremely well for considering solutions within my own head.

When all 5 of my brain cells agree on the path to take, I have the feature or fix already built and it just needs to be typed out in code. Afterwards, I take a look at the mess I've made and add documentation where things are not self-explanatory.

Collapse
 
shailennaidoo profile image
Shailen Naidoo

Whatever works for you, it is also case-dependent. What I mentioned in my article might not work for specific cases but to me it should be the default case.

Collapse
 
danbailey profile image
Dan Bailey

Yup. Back in the day, when I had stepped away from writing code, I was often writing functional specs. The devs on my team loved having those specs because they were written from someone who knew how to code, and I loved writing them because I got to interface with the devs and the business side of the equation. Now that I am back to developing, I usually scribble out a quick logical flow on the whiteboard to clear up my thinking and test ideas. Once I'm done with that, I write myself a "story" in the form of bunch of code comments, without writing the code. Then I write code. It gets me to the point where things usually work the first time, rather than my having to stumble around in the dark poking at random things. It works for me, by YMMV.

Collapse
 
shailennaidoo profile image
Shailen Naidoo

I have reached a point where I simply do not do anything without some kind of document to track decisions as those things must live on without you. I can develop entire features without running any of my code in the intended environment, I write everything as unit tests and then after everything works as expected I connect everything to the markup and see it work. It is a good practice as it allows you to code in your head entire features without looking at your machine.

Collapse
 
latobibor profile image
András Tóth

I have a more hands-on way because I burnt myself many times and also because of how my brain works: I love "spike" branches. I just toss around the code and write very stupid functions. There are things that only make sense when you get yourself dirty in the code; on a white-board everything always work.

With a clear goal though: coming up with the actual types required (say we are using TypeScript). When I have those at hand, I know my inputs and outputs.

With that knowledge, after seeing the non-negotiables of the reality of the codebase, then it is time for whiteboarding - though I personally prefer things like Miro, so I don't need to double-document.

Also you will need that high level documentation to reason about your changes, especially when people who don't understand the reality of the codebase and think the feature is going to be much smaller change.

Collapse
 
shailennaidoo profile image
Shailen Naidoo

There is no one-size-fits-all situation, it depends on so many factors.

Collapse
 
latobibor profile image
András Tóth

Exactly! My post was not a form of criticism, but to add to yours.

Collapse
 
tqbit profile image
tq-bit

because I haven't read it in the comments yet: A good maxime to follow is

"First solve the problem, then write the code"

Collapse
 
shailennaidoo profile image
Shailen Naidoo

I like this, I see that a lot of developers solve the problem by writing the code. To me this is a bad practice, first solve the problem via a document (layperson terms) and then implement the solution using code.

Collapse
 
ajborla profile image
Anthony J. Borla

Pithy, and wise, assuming it is the programmer performing both tasks.

However, isn't that the old world maxim ? From what I have been reading over the past year or so, it seems to me that the new world maxim goes something like:

Describe the problem to ChatGPT (or its brethren), let it code for you, massage the output, then happily take credit for using other people's code.

To some, there may not be a distinction between maxims. I sincerely hope the some does not grow in number.

Collapse
 
tqbit profile image
tq-bit

Love that statement.
At some point, AI might be advanced in a way that makes it capable of not spitting out (random) answers, but further questions. Imo, as a dev, you're not meant to solve problems by making assumptions, but making holistic decisions. If you do not know what questions to ask to solve an issue, gpt code gens will be coming for you very quickly.

Collapse
 
shailennaidoo profile image
Shailen Naidoo

For anyone interested, I thought that this article of mine dev.to/shailennaidoo/treat-onboard... is a good follow up to this current article.

Collapse
 
fullfull567 profile image
fullfull567

That's a really cool way of thinking about it

Collapse
 
shailennaidoo profile image
Shailen Naidoo

Thanks for thinking so, you are welcome to email me directly if you have any questions as I see that you are a novice so you might know what you do not know. You can email me at naidooshailen648@gmail.com

Collapse
 
asafalroy profile image
Asaf Alroy

This article is just accurate. I love it.

Collapse
 
junedang profile image
June Dang

This post remind me how we make money by solving problems rather than coding

Collapse
 
shailennaidoo profile image
Shailen Naidoo

Code is just an implementation detail, it is the building block for what is being architected. If I could not write code then that is what I would go for.

Collapse
 
anafi profile image
Anafi Abdul Bularis

Absolutely...
Understanding the user requirements and formulating a design specifications that can meet the user needs tops writing bunch of codes🤓

Collapse
 
shailennaidoo profile image
Shailen Naidoo

I 100% agree. Code should be the last part of the process. Identifying the requirements and how to breakdown work into stuff that is deployable and makes sense in terms of the longer vision for the project then everything should be alright.

Collapse
 
codingmaster97 profile image
codingmaster97

This is a really very interesting article.

Collapse
 
shailennaidoo profile image
Shailen Naidoo

Thank you @codingmaster97, if I had your handle, I would change it to writingmaster. Please share this article, I would greatly appreciate it.

Collapse
 
fnh profile image
Fabian Holzer • Edited

This can lead to a lack of accountability in the team and unintentional forms of gaslighting where people cannot remember that they agreed to something and when you raise it as a concern then it becomes a problem or it does not get taken seriously.

Welcome to the corporate world. As much as I love the written word as design tool and a healthy (=rather small) amount of design effort up front, nothing of it - no JIRA ticket, no word doc, nothing in the internal DMS or Wiki, will save your sweet behind from the blame game of the higher echelons once shit hits the fan. You are an IC. That's life and the deal we've all made under capitalism.

Collapse
 
shailennaidoo profile image
Shailen Naidoo

You are speaking facts! Someone needs to take on the blame, it also depends on company culture but surely it can be mitigated through good documentation.

Collapse
 
programmingdecoded profile image
Philip Perry

Very true. I just wrote up a story of a case where I didn't spend enough time writing and thinking through scenarios:
dev.to/programmingdecoded/fitting-...

Collapse
 
hg0428 profile image
Hudson Gouge

I have drawers full of papers with plans for projects and implementation details, algorithms, etc and I must say, it helps a lot to write.

Collapse
 
shailennaidoo profile image
Shailen Naidoo

It helps a lot when you print those documents and then things become tangible in the physical world.

Collapse
 
hg0428 profile image
Hudson Gouge

Mine are physical anyways so I don't even have to print them. They sit on my desk by my bed and I often get up in the middle of the night after somehow randomly solving a problem in my sleep.

Thread Thread
 
shailennaidoo profile image
Shailen Naidoo

Solving problems in your sleep happens.