I do programming, support and documentation for my company
to give you some perspective of where I am coming from.
It is critical for programmers to provide step-by-step documentation
for both the technical writers and those responsible for supporting
what is programmed.
As far as naming, there are a lot of obvious shortenings of
variable/function
names that are just as clear as the longer names. It is best to go for
clarity
regardless of length, but when naming functions and variables, tend toward
the
obvious abbreviations, i.e. auto for automatic, doc for document etc.
My understanding of self-documenting code (though I have not used the
Javadoc function
myself) is that each function begins with a general statement of what it is
supposed to
do and includes the developer name or source where appropriate. It is also
useful to include
explanation comments within functions where some action does not seem
obvious. This can also
be pulled out by javadoc to help techwriters document the code help support
personnel
identify where the problem is occurring.
-----Original Message-----
From: Shawn Zhu [mailto:[EMAIL PROTECTED]]
Sent: Friday, July 13, 2001 4:23 PM
To: [EMAIL PROTECTED]
Subject: off-topic: just a technical discussion about naming
It's off-topic, but I think for programmers
this may be sort of interesting discussion.
Lets start with a few questions:
What do you think it's a good practice for
documenting your code?
What does it means to have self-documenting
code?
There are people who believes using absolutely
english like phrases for variable/function names,
even if it means it'll be really long. I've seen
people coding with elaborously long names. However,
I'd say they don't really get what self-documenting
code really is all about.
Self-documenting code is clean with adequate documentation,
and easy to follow. With long names like that, it
clutters the view; it's error prone; it slows down
development process. The same can be said to long
documentations.
so what would you prefer long names or long documentations,
or something in between?
===========================================================================
To unsubscribe: mailto [EMAIL PROTECTED] with body: "signoff
JSP-INTEREST".
For digest: mailto [EMAIL PROTECTED] with body: "set JSP-INTEREST
DIGEST".
Some relevant FAQs on JSP/Servlets can be found at:
http://java.sun.com/products/jsp/faq.html
http://www.esperanto.org.nz/jsp/jspfaq.html
http://www.jguru.com/jguru/faq/faqpage.jsp?name=JSP
http://www.jguru.com/jguru/faq/faqpage.jsp?name=Servlets
===========================================================================
To unsubscribe: mailto [EMAIL PROTECTED] with body: "signoff JSP-INTEREST".
For digest: mailto [EMAIL PROTECTED] with body: "set JSP-INTEREST DIGEST".
Some relevant FAQs on JSP/Servlets can be found at:
http://java.sun.com/products/jsp/faq.html
http://www.esperanto.org.nz/jsp/jspfaq.html
http://www.jguru.com/jguru/faq/faqpage.jsp?name=JSP
http://www.jguru.com/jguru/faq/faqpage.jsp?name=Servlets
