DEV Community

Shailen Naidoo
Shailen Naidoo

Posted on

The best software engineers write instead of code

There is this misconception that software engineering comprises of several people getting together and writing code to meet an end goal but that is not what it is about. You will never see a car manufacturer building a car without some kind of plan, they have an entire dedicated team to the research and development of their next car.

Software engineering is the same process, whenever I try to develop something. I first close my IDE and do not even think of the code as the code is merely an implementation detail. In my document, I write what approaches I want to take when doing something or what it is that I am trying to achieve and from there, I start to flesh out the smaller implementation details of the project.

I would much rather write out the possible unit test cases as this is more important than the code itself. The code can be ugly, and it can be messy but as long as the unit tests pass and we have accounted for all the edge cases that we can identify upfront then I am happy with whatever is needed to achieve the desired goal.

You will often find that important decisions get lost if they are not tracked properly. 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.

I try my best now to ensure that any decision that is made by the team is tracked and acknowledged in writing before moving on to the next step, this will save you in the long run.

Top comments (33)

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.