My friend developer

I work with an amazing person. Every time I look in the bugzill or check my mail, I am amazed at it. Sometimes it seems to me that he could be a good writer. In any case, the graphomaniac is excellent.

This developer takes the documentation very close to the heart.

How he writes code

all classes with description

Each class, both public and protected or private, necessarily has a description. In the description - a few words about the class assignment, the name of the author, sometimes a link to adjacent classes, if necessary - the mark “For internal use only”.
')

all public methods with description

Each public method or constructor has a description of what this method does, what it returns, what parameters it accepts, what constraints on these parameters inflate, and sometimes what happens if the parameter has a trivial value (like null or -1).

checking parameters of all public methods

Each public method or constructor begins with validating incoming parameters. The conditions declared in the method description are checked. If at least one condition is not fulfilled, exception is thrown.

comments first

Very often a block of code (or one line) has a comment where it is explained in human language what is going to happen now. These comments appear before the code itself: the method signature is first determined, then its description is written, and then - in the method body - comments with an approximate execution plan (something like: “Check parameters”, “Connect to the database (here we are not connected) "," Execute such a request ").

class names, variables and methods are reasonable

These names follow a simple rule: the name of a method always begins with a verb, the names of classes and variables never contain a verb. Well, of course, the names of classes, variables and methods are chosen so that the code is easy to read even without comments.

How does he commit to VCS

every commit has a comment

In each comment for each commit, a description of why changes were made. Almost never - what has changed, but surely - why.

where possible comment refers to the number of bugs

If a commit fixes any bug, then the number is indicated by the bugs and its brief description (for example: "Fixed bug 999 (put Cthulhu back to sleep)").

How he leads the wiki

each subsystem has a page

Each developed subsystem has its own page. On this page - a few words about the purpose of the subsystem, if any, then links to PRD (Product Request Document, technical task), a few words about the implementation.

description of external interfaces

If the subsystem interacts with the outside world, then a description of open interfaces is given on the page (sometimes it’s just a link to the code documentation, sometimes to a WSDL, sometimes it’s just an example of a message). This is written for someone who will integrate with the subsystem (although, at the time of writing, this person may not exist).

Pictures

Very often the description contains a picture. This is either a UML diagram, or two or three multi-colored squares, or a screenshot of something useful. Pictures greatly facilitate understanding. Sometimes it is more effective to draw than to write.

every page change has a comment

The comment explains why the change was made.

How it works with bug-tracker

comment bugs upon receipt - ETA, complexity

If the bug is not trivial, then upon receipt a comment is written which explains why this bug is complex and approximately how long it takes to fix it. In any case, a mark is added that the bug is “accepted”.

dialogue with QA-engineer only via bug-tracker

Any questions, comments, suggestions - only through the bug-tracker. If something is discussed verbally (at a meeting or at dinner), then discussion theses are entered into the bug-tracker. Dialogue like: “And here, it seems, sometimes the left wing falls off!”, - “So I fixed it yesterday,” ends with a bug that closes immediately.

as soon as the bug is fixed and the fix in the closed bug

Not postponing until tomorrow, without doubting, the bug is marked as corrected.

when closing bugs, a comment is added with an explanation for the QA-engineer

The comment to the fixed bug contains two or three words about the fix and, sometimes, a hint for the QA-engineer how this fix is ​​easier to check and what it is worth testing again.

How he responds to e-mail

response time to any e-mail - no more than a day

For each e-mail reply is written on the same day. If it is impossible to answer the question immediately, then an explanation follows why and approximately when the answer follows. If the letter came to the wrong address, it is immediately forwarded.

E-mail is addressed only to those who should

Each letter sent, be it a question, comment, gratitude, suggestion, is addressed only to those people whom it is important to read it. For example, an e-mail about a change in the structure of a class in the CC does not add the company's CEO and secretary girl.

in each e-mail - the words "thank you" and "all the best"

Each e-mail begins with words of gratitude (for a question, comment, suggestion) and ends with polite words of farewell like “best regards”, “have a nice day”.

Once I asked this geezer why he does all this. He replied that he had a terribly bad memory for little things. When he needs to remember something, he looks in the code, CVS, buzill'u. He replied that it was easier for QA-engineers because they could look at the progress of the work and write complete test plans. He replied that it was more convenient for managers, because they can judge the timing and complexity of the subsystems. He replied that it would be easier for other developers to deal with his code. He replied that it would be easier for other developers to reuse its code. He replied that Steve McConnell taught that.

I thought: "Well, not a maniac?". Do you think he is a graphomaniac or just a good developer?