Software development guidelines
In the process of software development, other people may come and maintain and extend your software. This is especially true if you develop software in groups. For other people to understand and maintain software, some commonsense software development guidelines should be followed.
In general, the software should aim for end users to be able to use the software optimally, and for developers to expand and maintain easily.
Guidelines
In essence, keeping the seperate functionality of your program in logical components such as functions or subroutines will aid in understanding the processes taking place in your program.
In larger programs, splitting your program up into modular components that interact according to standard, pre-specified interfaces will aid in updating the software greatly. This allows faulty code to be taken out and replaced with working code - and because the components interact through the common interface, and the component still adheres to that interface, the software will work instantaneously with the working code. This also means that the entire software codebase need not be recompiled since only the component needs to be.
- http://www.leshatton.org/Documents/OO_IS698.pdf has a really neat section in it about these issues.
Ease-of-use
However, your users must be able to interact with your software successfully.
In general follow the user interface guidelines for the environment that you are using. Software that does not appear to be consistent with other software will both confuse and aggravate the end user.
It may be useful to provide helpful error messages that can help lead to solving or the problem. It may also be of note that the user should not be overladen with technicalities - for example a stack backtrace may not be a helpful thing to include in an error message in a software package that is not aimed to technical-minded users.
Good documentation is always necessary, but it is even better that the software does not impinge on the user to the extent that the user should rely on it. The software should be intuitive enough for the user not to need the documentation.
For asking for input from the user, it may help that sensible defaults are prefilled for these inputs.
Field usability testing is often an invaluable way to examine how end-users interact with your software, and will provide instantaneous feedback on your software and its interface. If you think of yourself as being a new end user, this may help you avoid interface problems also.
Eric S. Raymond has an article called "The Luxury of Ignorance" along with a followup - check it out.
Why adhere to these guidelines?
The major costs of software are retraining and maintanance. There may be extra costs if the software fails, causing loss of productivity or property damage, or even loss of life. In commercial software development, the company that you may be working for way warrant or guarantee that the software should work as it should. If you are developing code and do not adhere to these guidelines, it will make your life as well as the lives of your colleagues more difficult as the code will become more cryptic, and thus harder to maintain and improve.