Effective programmers consider their work a craft.
If you really desire to program well, a first step is to take pride in your work—
pride enough to sign your name on everything you do. Through the centuries,
fine furniture makers signed their work, painters finished their efforts by dabbing
on their names, and authors inscribed their books. Programmers should
stand behind their creations.
Computer software has the luxury of immediate copyright protection—it is
a protection against piracy, and a modern statement that you stand behind the
belief that what you do is worth fighting for. If you have crafted something as
best you can, add a comment at the top of your code:
// HBE Foundation .
// (c) 2015, 2016 Badmus EniRe
If, of course, you have stolen work from another, avoid the comment and
consider, heavily, the appropriate attribution.
Comments are not necessary, but documentation
makes working with a program much easier. One of the most important comments
you can provide is your name—it suggests you are taking credit and responsibility
for things you create. It makes our programming world less anonymous
and more humane. An assumption you make about the state of your program. In
Java, we will encode the assertion as a call to a function that verifies the state
of the program. One side effect of this relationship is that we have all been reminded of the need to write comments. If you do not write comments, you will not be able to
read the code. If, however, you design, document, and implement your interface
carefully, you might not ever have to look at the implementation! That’s good
news because, for most of us, in a couple of months our code is as foreign to
us as if someone else had implemented it. The end result: consider yourself a
user and design and abide by your interface wherever possible. If you know of
some public field that gives a hint of the implementation, do not make use of it.
Instead, access the data through appropriate methods. You will be happy you
did later, when you optimize your implementation.
Special comments, including conditions and assertions, help the user and
implementation of a method and determine whether the method is used correctly.
While it is difficult for compilers to determine the “spirit of the routine,” the
implementor is usually able to provide succinct checks of the sanity of the function.
Five minutes of appropriate condition description and checking provided I’ve done my
by the implementor can prevent hours of debugging by the user.