See the Light
12 Strings
A Reason To Succeed
The greatest compliment you can pay a teacher, coach, or mentor is to succeed.
A Chipmunk, A Squirrel, A Bird, and A Fox
Romee
A Man And His Dog
Dog Whispering
It’s The Little Things
Some may say “don’t sweat the details” and I would reply, “but it’s the little things that make it great”.
The attention paid to the finer details of code will always play an important part in how well the code works. The documentation written to excess will only serve to better explain the code down the road when updates and improvements are made. This is not to mention the great benefits it will also serve when other developers start working with the code.
Almost anyone can write good code, it really doesn’t take much with today’s search tools and the wealth of knowledge shared in the developer communities, but …
… sweating the details is what great code is all about; and this new project is being kept to this basic tenet.
Beginning A New Project
Although I have been considering this idea for some time I only just recently started putting code to (digital) paper on a new project … and, yes, it is WordPress related. What can I say? I really enjoy working with the platform.
Now, the reasons I am writing this here:
- I am still available for other projects … just letting everyone know this one is important, too.
- I am approaching this project from an entirely new view point
- I know this will be good for the community
- I know this will be good for myself
Once I am satisfied most of the features are working in a stable alpha-code state I will be looking for some adventurous individuals …
… but, what is this new project?! Stay tuned for more information.
Code Documentation
Some may say the code is the documentation … and others may reply with the documentation is the code. I believe both are true; and, more importantly, they are not mutually exclusive.
First off, the code quality should be (if possible) in a format that is easily (human) readable. The idea is to provide the person looking at the source code an easy-to-follow layout as well as providing sensible separations between the various code structures.
The code should also be semantically written using naming conventions that help explain why each code construct exists, as well as providing an appropriate indication of what the code will do.
The above two ideas do not preclude the requirement for document blocks to be also included as appropriate in the code, as well as additional code comments explaining specific details that may not be readily apparent from reading the code.
Essentially, the point of view I recommend with documentation is quite simple:
Imagine it is six months later and you did not write the code yourself. Does the documentation you provided properly explain the who, what, where, when , and why of the code? … because in six months time, if you have not been working with the code all along, it will likely be just like you never wrote the code in the first place. Now, imagine what another developer would be going through.
Good UX is not solely in the realm of the end-user.
Most importantly, write the inline documentation when developing the code. You will find it much easier to write the documentation while you develop the code versus going back after the fact and writing it then.
Also, I find it much easier to focus on the task at hand if I do the document framing (read: basic outline) prior to writing the first code structure. Ideally this will also provide the scope of the code as well.
It’s All Over Now
… the end is nigh; now, if you will excuse me, I’m going to follow Chicken Little across the road.
Life does not have to be taken so seriously … enjoy it while you can!
Coding Standards
Over the last 15 or so years, I have learned many things about writing code; about documenting code; and, about providing support for this same code, too.
Coding Standards
When writing code, I make every effort to keep a consistently structured format with the use of white-space, tabs, etc. This helps to provide clear delineation of code elements and structures, but more so it provides easier to read code. If code is easy to read, it is easier to understand.
In my opinion, this is a hallmark of quality code. I cannot recommend strongly enough how important it is to keep a project’s code consistently structured, formatted, and documented. If this is not consistent, it could easily give an impression the project itself is not consistent … or worse, flawed?! It’s also much easier to edit well structured code.
My structuring convention, since I tend to focus on WordPress related projects, is very similar to the coding standard documented on their codex page: WordPress Coding Standards.
A project’s code should also implement a consistent version number convention. This can be as simple or detailed as you want but I would recommend it also have its own explanatory documentation.
For example, a recent article I read regarding the Semantic Versioning Specification provides “a simple set of rules and requirements that dictate how version numbers are assigned and incremented.” I’ll likely be adopting this, or a very similar specification for my projects.
Another important coding standard is using a consistent naming convention:
In computer programming, a naming convention is a set of rules for choosing the character sequence to be used for identifiers which denote variables, types and functions etc. in source code and documentation.
Wikipedia – Naming Conventions (programming)
The keys to quality coding standards are these:
- adopting and/or creating documented specifications; and,
- being consistent in how they are applied.