From 97e479811a290527c890a73ba04105380dfc5b09 Mon Sep 17 00:00:00 2001 From: Karan Jayachandra Date: Wed, 4 Feb 2026 14:36:20 +0100 Subject: Cleaned up the software engineering post --- content/posts/software_engineering.md | 87 ++++++++++++++++------------------- 1 file changed, 39 insertions(+), 48 deletions(-) (limited to 'content') diff --git a/content/posts/software_engineering.md b/content/posts/software_engineering.md index 12bcc1c..de19077 100644 --- a/content/posts/software_engineering.md +++ b/content/posts/software_engineering.md @@ -3,56 +3,47 @@ title = "Notes on Software Engineering" date = 2025-02-04 +++ -I worked at a large software company, [SAP](https://www.sap.com) for three years. But I didn't get to learn much about software engineering. SAP has its own tools and process that have already dictated how things work. But over the years, I have realized how important software engineering can be. Here I outline some of the lessons I have learnt (some with a lot of pain) about this. - -Key Learnings: -- Don't reinvent the wheel -- Craft bespoke only when needed -- Code is a liability; tame it and limit it. -- Automation isn't always necessary. ---- -Write simple code. Use existing [data formats](https://stackoverflow.com/a/27713489). You don’t need inheritance, you don’t need that shiny new data structure. Keep to the basics and things will be much more easy to manage in the long run. It is not about how many lines of code but how few lines of code. Reduce the number of moving parts. - -The [Joel Test](https://www.joelonsoftware.com/2000/08/09/the-joel-test-12-steps-to-better-code/) is a great way of pointing you in the right direction: -1. Do you use source control? -2. Can you make a build in one step? -3. Do you make daily builds? -4. Do you have a bug database? -5. Do you fix bugs before writing new code? -6. Do you have an up-to-date schedule? -7. Do you have a spec? -8. Do programmers have quiet working conditions? -9. Do you use the best tools money can buy? -10. Do you have testers? -11. Do new candidates write code during their interview? -12. Do you do hallway usability testing? - -[Taste](https://www.seangoedecke.com/taste/) and skill are different! Taste is dependent on your values. An immature engineer is inflexible in taste. - -Sajid on YouTube has created a really good [resource](https://www.youtube.com/watch?v=vvPklRN0Tco) - -Documentation: Maintain at least a [README](https://www.makeareadme.com/) file. -## Tools -### Terminal -Learning to use the terminal will be much more efficient in the long run. You will be able to do basic tasks as well as complex ones using just the keyboard. GUIs also take up much needed space on the screen as well as in your brain with distractions. The terminal is as distraction free as it can get when using a computer despite all the [arguments](https://jvns.ca/blog/2025/02/05/some-terminal-frustrations/) against it. I found that the Linux shell is much better to use specifically [ZSH](https://ohmyz.sh/) using WezTerm. -### Editor -VS Code because I am casual but I would eventually like to switch to neovim. -### Version Control -Even if you are the only person working on a project. Use [git](https://git-scm.com/). This is crucial. If you want to work with other, it is doubly more important. git is not restricted to software projects but any text files that require frequent revision. Even this blog is under version control. Do not have 10 versions of your code floating around. Work on two branches, `main` and `feature\` and keep them regularly in sync. [Beej’s guide](https://beej.us/guide/bggit/) is an excellent resource. -- Keep the repository clean and with text files only -- Link unrelated project with sub-modules -- If large files need to be store use the Large-file Storage (LFS) feature -- Common commands: clone, add, commit, pull, push, checkout, branch -- If you need to remove old git history, use the git-filter-repo tool -- Merge source code form different repositories by adding a new “remote” +I worked at a large software company, [SAP](https://www.sap.com) for three years. But I didn't get to learn much about software engineering. SAP has its own tools and process that have already dictated how things work. But over the years, I have realized how important software engineering can be. Here I outline some of the lessons I have learnt (some with a lot of pain) about this. If you are reading this and don't know where you or ytour team stands on software engineering, take the [Joel Test](https://www.joelonsoftware.com/2000/08/09/the-joel-test-12-steps-to-better-code/). + +### Terminal is the superior interface + +Learning to use the terminal will be much more efficient in the long run. You will be able to do basic tasks as well as complex ones using just the keyboard. GUIs also take up much needed space on the screen as well as in your brain with distractions. The terminal is as distraction free as it can get when using a computer despite all the [arguments](https://jvns.ca/blog/2025/02/05/some-terminal-frustrations/) against it. I found that the Linux shell is much better to use and to script with. + +### Version control is a programmer's best friend + +Even if you are the only person working on a project, use version control. When working with others, a software project without version control is not professional. [git](https://git-scm.com/) is a popular one but [jj](https://www.jj-vcs.dev/latest/) also shows promise. You can also use git for any files that requires multiple revisions. This web site is also under version control. [Beej’s guide](https://beej.us/guide/bggit/) is an excellent resource to understand git. Try to keep your branches and history clean. Large files are not git's forte. Git FLS is a better choice there. + +### Keep it simple stupid + +Write simple code. Simplicity is hard; complexity for complexity's sake is forbidden. Keep to the basics and things will be much more easy to manage in the long run. Code is a liability; tame it and limit it. I postulate that the more you can manage to do with the fewer amount of code, the better you are as a programmer. [Cognitive load is what matters](https://minds.md/zakirullin/cognitive). Create clean interfaces and make your program do one thing and one thing well as stated in the UNIX principles. [Do the simplest thing that could possibly work](https://www.seangoedecke.com/the-simplest-thing-that-could-possibly-work/). + +### Don't reinvent the wheel + +A lot of programming problems have already been solved. This doesn't mean you cannot come up with an alternate solution but first examine and use the existing one. When you hit a limitation, try to improve the existing solution. Craft bespoke when it cannot be avoided. Take this with a pinch of salt though. Sometimes, creating a specific tool or piece of software is essential. As engineers we want to use our own work rather than someone else's. This especially applies for data formats. Stay away from creating new data formats. Use existing ones like CSV, XML, [HDF5](https://stackoverflow.com/a/27713489) or even plain text. Watch [the unreasonable effectiveness of plain text](https://www.youtube.com/watch?v=WgV6M1LyfNY) for a much better case to be made for using plain text. + +![How standards proliferate](https://imgs.xkcd.com/comics/standards.png) + +### To a hammer everything is a nail + +Using the right tool for the right job is crucial. One could use C programming for frontend development or JavaScript for numerical computing, however the right programming language or framework usually is dictated by your software requirements. One could be really skilled in a particular language but being able to use a broad set of skills but as an engineer one has [taste](https://www.seangoedecke.com/taste/) as well. They are different! Taste is dependent on your values. An immature engineer is inflexible in taste. Try to get an overview of the landscape and choice the best fit tool for the job. + +### To automate or not to automate + +![Is it worth the time?](https://imgs.xkcd.com/comics/is_it_worth_the_time.png) + +Automation isn't always necessary. For activities that don't need to be repeated, things don't have to be done cleanly. However one needs to keep in mind that the above chart doesn't take into account if multiple people repeat the task. Automation also brings benefit in terms of consistency (all the results looks the same) and prevents errors in processes that are repeated many time. Humans are not made to repeat the same thing over and over again, we fail at it terribly. + +## A bit of documentation goes a long way + +Maintain at least a [README](https://www.makeareadme.com/) file. This allows for people to understand what you are trying to do. Comments in code should describe what is being done, the code should do this. Comments are to be used to describe why something was done in a particular way. Even documentation should be limited because someone will have to maintain it. Documentation should help either the user or the developer, if not, it isn't necessary. + +## Tooling defines the friction in your process + +Simple, fast and open tools are usually better in most cases. They allow for quick onboarding of team members, easy deployment of work and access to a larger community of experts. Understanding your tools also goes a long way in helping improving processes. A developer should be fighting with his tools; the tool should augment the performance of the developer. Standardize tools if possible but engineers usually bring a carefully crafted and deeply personal toolset with them; account for this. ## References -- [Cognitive load is what matters](https://minds.md/zakirullin/cognitive) + +- [21 Lessons from Google](https://addyosmani.com/blog/21-lessons/) - [Big O](https://samwho.dev/big-o/) -- [Tigerstyle](https://github.com/tigerbeetle/tigerbeetle/blob/main/docs/TIGER_STYLE.md) - [Periodic Table of System Design](https://github.com/jarulraj/periodic-table) -- [Tiger Style](https://tigerstyle.dev/) - [Refactoring Guru](https://refactoring.guru/refactoring/catalog) -- [21 Lessons from Google](https://addyosmani.com/blog/21-lessons/) -- [Is it work it](https://griffin.com/blog/is-it-worth-it) -- [Sean Goedecke's Blog](https://www.seangoedecke.com/) \ No newline at end of file -- cgit v1.3.1