Dec 2, 2016
The purpose of this article is to explicitly define the language agnostic anatomy of a source code file. I may fail in defining a one-size-fits-all solution, but that is my goal. Embodied in this goal, I want to explicitly identify where and in what order documentation and specific sectionalized-code-divider-labels should reside within a file.
This is not rocket
appliances science. This is disciplined and consistent code sectionalization regardless of programming language. Ideally, implementing this approach results in a UX boost for source code authors.
Many developers (in one form or another) already sectionalize each code file they author. I notice however that some developers do not (my old-developer-self included). This lack of sectionalization irks me. It irks me more when I switch to authoring in another language where the sectionalization is either absent or inconsistent from the language previous. In times like these, I pay a greater "mental tax" than that which is inherent to the language context switch itself.
I have thought about this inherent "mental tax" (or "mental burden") that is endured by other developers who write in more than one language daily (or at least often). This "tax" is a function of how dissimilar the mechanics, authoring environment, and syntax are of the languages in question. I want to reduce this tax.
Firstly, I don't think I am the first person to do this and I would almost guarantee that many programmers do something similar to what I propose below. Do you? Is there standard you know of?
The implementation of my proposal is dead simple. Simply insert the eight ordered single-line comments with the following section divider labels into a source file:
Additionally, there are eight corresponding questions to ask yourself to help determine what code belongs within each section of a given file (if it isn't already obvious):
These eight section divider labels can be subgrouped:
In honesty, I go back and forth regarding the need to explicitly insert the first three section dividers in a file: Documentation, Dependencies, and Definition. This is because every source code file I have seen, regardless of language, follows the same pattern implicitly (documentation being less of a given experientially). I identify them here for completeness. Their insertion in practice may be considered noise, but their acknowledgment here is important.
The real meat is nested within the Definition. Below are the remaining section divider labels accompanied by some notes regarding order and purpose:
So far there has been a lot of textual description. This has been intentional. I wanted to detail my thoughts regarding this simple idea rather than only presenting examples. My hope in doing so influences fellow developers to provide input on my thought process. For those wanting examples, your time has come: C# (Unity3D) and TypeScript (Angular 2).
The samples below have been updated with my eight aforementioned section divider labels. Prior to the update, they did indeed contain section dividers, but the labels and count were inconsistent across languages.
I know the likelihood is slim that the eight previously proposed section-divider-labels will suffice for all programming languages (there are a shit-ton of languages). That does not stop me from trying. I want to grasp if this is a feasible effort or if this effort should tighten scope.
All in all, I am looking for the input of others with regard to their:
If you have improvement ideas or any other thoughts, just reach out on Twitter @derekknox or email me derek [at] derekknox.com. I look forward to any input and I hope you enjoyed the read.