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)
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.
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.
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.
Also diagraming tools like draw.io or mermaid.live (or a vscode mermaid plugin for that matter)
+1 for Obsidian. Been using it for 2 years now
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.
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.
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.
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.
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
typesrequired (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.
There is no one-size-fits-all situation, it depends on so many factors.
Exactly! My post was not a form of criticism, but to add to yours.
because I haven't read it in the comments yet: A good maxime to follow is
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.
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:
To some, there may not be a distinction between maxims. I sincerely hope the some does not grow in number.
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.
For anyone interested, I thought that this article of mine dev.to/shailennaidoo/treat-onboard... is a good follow up to this current article.
That's a really cool way of thinking about it
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
This article is just accurate. I love it.
This post remind me how we make money by solving problems rather than coding
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.
Absolutely...
Understanding the user requirements and formulating a design specifications that can meet the user needs tops writing bunch of codes🤓
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.
This is a really very interesting article.
Thank you @codingmaster97, if I had your handle, I would change it to writingmaster. Please share this article, I would greatly appreciate it.
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.
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.
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-...
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.
It helps a lot when you print those documents and then things become tangible in the physical world.
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.
Solving problems in your sleep happens.