There are many articles and resources that guide developers on how to write “clean code.” In A Guide on How to Write Clean Code [1], Maryam Dashtirahmatabadi lists seven rules to follow that will result in “clean code,” including principles of DRY (Don’t Repeat Yourself), SOLID [2], with a few more general rules like “Write testable code” and “Code should be readable.”
These are all good tips but the article is brief, and Dashtirahmatabadi doesn’t quite touch on the implications of writing “clean code.” In another article I read, The Art of Writing Clean Code: A Key to Maintainable Software [3], the author touches on the real importance of writing code that is maintainable for future developers and collaborators. It is the obvious requirement that good code can be compiled (or interpreted) by a machine, but it is equally important that our teammates and other contributors can parse out vital information from our code base(s).
My experience so far in the capstone project has been mostly developing solo, but this week we had a meeting in which I walked through my code. I opened files and explained what each method and component does, while running the project locally. This went well overall but it certainly exposed many weak points, inconsistencies and redundancies that we clear to me, even though I had just written most of it in the last two months.
Something that is contributing to the slight mess is that I am trying to implement server methods with varying degrees of security in mind; some things should be designed poorly, with the intent of changing the code between different variations of the entire app. This has led to some whole segments intentionally commented out, with vague notes about what might be a better practice.
The snippet above shows a clear example of bad coding practice, with a comment about what might be a better idea.
A big hurdle this term is going to be organizing how we handle these types of variations. We have discussed having multiple branches in the repository that will deploy versions of the application with varying levels of security. This introduces a more general scope of clean code; organizing branches and providing clear instructions and documentation about how to use them.
In the same code, there is an example of good commenting. When another teammate initially read through the code, they added comments for each dependency and some of the initial setup steps:
I look forward to the rest of this quarter, because more of the team is going to start developing, and there will surely be questions about best practices, refactoring and cleaning up small messes that will contribute to a better product overall.
References
- https://medium.com/swlh/a-guide-on-how-to-write-a-clean-code-776ce278755f
- https://en.wikipedia.org/wiki/SOLID
- https://reflectoring.io/clean-code/
