tag:blogger.com,1999:blog-21179782.post9190425788815062198..comments2015-09-10T18:27:41.393-04:00Comments on Ninja Software Development: No Comment!Dixie Software Ninjahttp://www.blogger.com/profile/03037941824583012175noreply@blogger.comBlogger2125tag:blogger.com,1999:blog-21179782.post-76786056230556467402008-12-17T21:14:00.000-05:002008-12-17T21:14:00.000-05:00I'm not convinced the "how" part is necessary exce...I'm not convinced the "how" part is necessary except in very rare cases.<BR/><BR/>I'm also not a big fan of function headers that are longer than 3 sentences. In my experience, the parameters' names give the necessary infoDixie Software Ninjahttps://www.blogger.com/profile/03037941824583012175noreply@blogger.comtag:blogger.com,1999:blog-21179782.post-91582330944592052122008-12-16T10:14:00.000-05:002008-12-16T10:14:00.000-05:00I think there are three types of comments, what, w...I think there are three types of comments, what, why, and how.<BR/><BR/>What: On top of the code. List the purpose, the parameters, and if the logic is complex, the basic approach that will be taken.<BR/><BR/>Why: Explain at each assertion, assumption, exit point, or variable reset why they are being done then.<BR/><BR/>How: When a particular step of the What is being implemented, explain this is where it is being done (like an HTML anchor), or this is how it is being done.<BR/><BR/>In all cases, the name of a subroutine can also act as a comment. But if it isn't obvious, explain it. One minute explaining something while "in it" can save tens of minutes, if not hours, when not "in it".Brian Tkatchhttps://www.blogger.com/profile/11320700842381820277noreply@blogger.com