Alexander Zuban’s Homepage

Here is some my thought about java doc.

Personally me sceptical about putting lots of javadoc and examples of usage in javadoc.

The reasons I say so:

• Due to human nature nobody in the project will read them.
• Most of projects are business oriented, and not used as a public library, so javadoc is not such critical, so your code will not be used as a black box by many developers all over the world
• I believe that the code should be the primary documentation because it has all the details, when developers looking into code they are getting better understanding of the things and can change them in more desired way.
• Support of javadocs will add additional time overhead and will make refactoring task more complex (or after the code refactoring javadoc will be dirty).
• In 90% cases, javadocs created by developer not give more information then method signature, e.g. javadoc for the function getFile will be “This method return the file”.
• For the distributed team specific (people who working 10-15 hours per week) spend 1-2 hours to put javadocs looks too prodigally as for me.

So I am follower of the idea, that code should be understandable in the same level that javadoc and instead of putting code example into the comments, it is better to create a JUnit test.

Some examples of the comments-javadocs I saw recently:


/**
* Construct object instance with default parameters.
*/
public SomeClass(){
...
}



/**
* Registers new listener.
*
* @param l
* the listener to register.
*/
public void addChangeListener(ChangeListener l) {
...
}


// Start transaction.
session.beginTransaction();
....
// Commit all changes.
session.commit();


Well, as for me such comments just add additional lines to code and make it harder to read(good that eclipse has folding feature for the method javadoc).

So again, javadoc is very useful for open source projects, but I am skeptical about using them in business related projects, and developers can’t write good javadoc documentation.

No Comments »

Have you ever manage servers over internet? Yep! There is some pain with this. When you look at the black putty screen and command “reboot”, this is like give a “submerge” command to submarine. “- Submerge! … The system is going down for reboot NOW! …Five, Fore, Three, Two, One, Zero… Check it!”. And if you have a bit of luck you will see login prompt again, in other case server will sink and stop responding. This means that you need to touch data center support or drive to data center. There 1000+ reasons why server may not surface. So there are some simple rules to avoid such things:

• if you put some scripts, make sure that the syntax correct. You may do this just with sending main commands to standard output
• use common distribution (more probably it is tested by other people and they report about bugs before you)
• reboot server after major configuration or software updates( to make sure that you Docbase, or DB will come back )
• keep your system up-to-date, so it will not unexpectedly crash
• keep in mind that hardware even less reliable then soft, so duplicate (or backup) your data

Also if you have KVM switch installed this is like a periscope, but into your submarines This gives you additional degree of freedom especially when you installing kernel updates.

So server submarine on top… Hip Hip Hooray!

No Comments »