The greatest compliment you can pay a teacher, coach, or mentor is to succeed.
Sounds like the beginning of a joke but actually it was all we saw when we visited the Elora Gorge Conservation Area yesterday on our May vacation.
You would think there would be more to see in a place that is surprisingly larger than one would expect but that was about it … now the really funny thing about this little excursion is although we now have “dueling” Canon T3i cameras we did not get a picture of any or these elusive denizens of the gorge.
There was lots to see in Elora though and the following gallery is a sample of some of the things we did get pictures of.
Introducing our Romee, a male Shih-Poo.
He’s been with us for nearly a year and a half now … and although there really has not been any reason to not write about him before I simply could not resist posting a couple of pictures taken yesterday afternoon by my wife, Terri.
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.
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.
… 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!
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:
A client is only as good as you treat them; so, if you want the best clients you need to treat them that way.