Categories

See More
Popular Forum

MBA (4887) B.Tech (1769) Engineering (1486) Class 12 (1030) Study Abroad (1004) Computer Science and Engineering (988) Business Management Studies (865) BBA (846) Diploma (746) CAT (651) B.Com (648) B.Sc (643) JEE Mains (618) Mechanical Engineering (574) Exam (525) India (462) Career (452) All Time Q&A (439) Mass Communication (427) BCA (417) Science (384) Computers & IT (Non-Engg) (383) Medicine & Health Sciences (381) Hotel Management (373) Civil Engineering (353) MCA (349) Tuteehub Top Questions (348) Distance (340) Colleges in India (334)
See More

Documentation style

Course Queries Syllabus Queries
Max. 2000 characters
Replies

usr_profile.png
Amie Khalifa

User

( 6 months ago )

From the syllabus for one of my programming classes: "Your documentation will be sufficient if it would be possible to read only the comments, without looking at the code, and explain what the code does."

Have any of you heard of a documentation style like this? Is it a good practice? Seems extremely overzealous to me.

usr_profile.png
Garry Buttler

User

( 6 months ago )

 

Code should be easy to follow. This can be achieved in a number of ways:

  1. appropriate and meaningful naming
  2. commenting on especially difficult algorithms or complex code
  3. extensive documentation of all the code

Appropriate documentation will use all three approaches where they are appropriate.

However, when the audience for the code is primarily trying to understand the code and assess understanding of the concepts - ie in an academic context, the third one is likely to be highly desirable.

All code should be written and documented so that it can be understood by your worst detractor, when he is on callout at three o'clock in the morning because there is a problem with the production system.

At the same time, excessive comments are another item to be maintained, and kept in sync with the code when changes are made to the code, and comments are the least likely item to be properly maintained under change.

what's your interest


forum_ban8_5d8c5fd7cf6f7.gif