Java   View all facts   Glossary   Help

syntactic unit > comment

comment
subject			fact

comment	can be written before writing the code
	can precede package statements
	has example executeMe(); // doNotExecuteMe
	has example executeMeToo(); /* This is to be ignored and this too */
	has purpose to describe the purpose of each class, method and variable along with any difficult-to-understand statements inside methods, and to indicated any changes to the code
	has syntax '/*' comment '*/' or two slashes '//' indicating that the rest of the line is to be considered a comment
	has syntax /** commentText */ OR /* commentText */ OR // commentText Note: '//' ignores everything to end of line
	is essential to give readers an overview and to help them understand its complexities quickly
	is a subtopic of Java Basics
	is a kind of syntactic unit
	should be between about 20% and 35% of the total length of the code
	should be written to describe each non-obvious variable
	should be written to describe loops and conditional statements inside complex algorithms
	should be written at the head of each non-obvious method describing its function and usage
	should be written at the top of each class
	should describe the purpose of the class, how it should be used, its authors and its history of modification
	should not be about obvious things since they add clutter
syntactic unit	has syntax rule bold = mandatory italic = non-terminal normal font = optional

Next syntactic unit: declaration    Up: syntactic unit    Previous syntactic unit: clause