Click here to Skip to main content
14,664,191 members
Home » Discussions » Work Issues
   

Work Issues

 
GeneralRe: How to write a programming language in Hindi? Pin
Member 1349103923-Nov-17 4:26
MemberMember 1349103923-Nov-17 4:26 
GeneralRe: How to write a programming language in Hindi? Pin
INDtanay23-Nov-17 6:01
MemberINDtanay23-Nov-17 6:01 
GeneralRe: How to write a programming language in Hindi? Pin
Member 1349103927-Nov-17 17:07
MemberMember 1349103927-Nov-17 17:07 
QuestionWorking with software houses / SDLC expertise Pin
JohnLBevan4-Oct-17 0:30
professionalJohnLBevan4-Oct-17 0:30 
SuggestionDrop Down Issue Pin
Member 1332500523-Jul-17 21:04
MemberMember 1332500523-Jul-17 21:04 
GeneralRe: Drop Down Issue Pin
Richard Deeming24-Jul-17 8:07
mveRichard Deeming24-Jul-17 8:07 
QuestionOf Code and Comments Pin
I.explore.code30-Jun-17 8:19
MemberI.explore.code30-Jun-17 8:19 
AnswerRe: Of Code and Comments Pin
David A. Gray30-Jun-17 9:22
MemberDavid A. Gray30-Jun-17 9:22 
I've been writing software for almost 40 years, and I'll take your bait. Wink | ;)

As is the case with almost every engineering issue, there is a fine line between appropriately commenting code and commenting just to fill a space. To that end, I think you are partially correct, but I think we differ in three key respects, unless I misunderstood you.
  • Every function or method should be prefaced with a short explanation of the algorithm that it implements or the task that it performs. Obviously, if the function is part of the public interface, this comment should take the form of an XML comment, which need not be repeated as a regular comment. You can also make a good case for attaching XML comments to every method. Indeed, I usually follow this practice in my own work, and I've seen it often in the work of others.
  • Every class must begin with a short explanatory comment about its purpose. As is the case with methods, this can take the form of XML commenting.
  • Every module must contain a change log, and you must be fastidious about adding a note, brief though it may be, every time you change it.
With respect to the third point, some would argue that this is the purpose of check-in comments, but my experience has been that these are almost invariably insufficient to properly document what changed, and why a file was included in a given changeset. I have wasted many valuable hours, usually aided by side by side changeset comparisons, to obtain such knowledge, which would be ridiculously easy to put into a change log. In my view, the changeset log is just not sufficiently granular to be your whole change history.

Finally, in the first point, I mentioned attaching XML comments to all methods. The benefits of doing so are twofold.

1 Since IntelliSense picks up local XML comments, it's easier to consume provate methods in other parts of the same project.

2 If you decide later to make a class or method public, the XML comments are already there, so the only required change is to the access modifier.

While I agree with you that commenting can be used to compensate for sloppy code, there are some things that just cannot be documented by the code alone.
David A. Gray
Delivering Solutions for the Ages, One Problem at a Time
Interpreting the Fundamental Principle of Tabular Reporting

GeneralRe: Of Code and Comments Pin
I.explore.code30-Jun-17 10:19
MemberI.explore.code30-Jun-17 10:19 
GeneralRe: Of Code and Comments Pin
David A. Gray30-Jun-17 10:33
MemberDavid A. Gray30-Jun-17 10:33 
GeneralRe: Of Code and Comments Pin
I.explore.code30-Jun-17 12:55
MemberI.explore.code30-Jun-17 12:55 
GeneralRe: Of Code and Comments Pin
David A. Gray5-Jul-17 16:02
MemberDavid A. Gray5-Jul-17 16:02 
GeneralRe: Of Code and Comments Pin
I.explore.code14-Jul-17 13:13
MemberI.explore.code14-Jul-17 13:13 
GeneralRe: Of Code and Comments Pin
Davie2124019-Feb-18 10:43
MemberDavie2124019-Feb-18 10:43 
AnswerRe: Of Code and Comments Pin
Foothill30-Jun-17 9:59
professionalFoothill30-Jun-17 9:59 
GeneralRe: Of Code and Comments Pin
David A. Gray30-Jun-17 10:30
MemberDavid A. Gray30-Jun-17 10:30 
AnswerRe: Of Code and Comments Pin
Eddy Vluggen1-Jul-17 0:21
professionalEddy Vluggen1-Jul-17 0:21 
GeneralRe: Of Code and Comments Pin
I.explore.code1-Jul-17 6:50
MemberI.explore.code1-Jul-17 6:50 
GeneralRe: Of Code and Comments Pin
Eddy Vluggen1-Jul-17 7:34
professionalEddy Vluggen1-Jul-17 7:34 
GeneralRe: Of Code and Comments Pin
I.explore.code1-Jul-17 9:14
MemberI.explore.code1-Jul-17 9:14 
GeneralRe: Of Code and Comments Pin
Eddy Vluggen1-Jul-17 10:05
professionalEddy Vluggen1-Jul-17 10:05 
GeneralRe: Of Code and Comments Pin
I.explore.code1-Jul-17 13:33
MemberI.explore.code1-Jul-17 13:33 
GeneralRe: Of Code and Comments Pin
Eddy Vluggen1-Jul-17 23:27
professionalEddy Vluggen1-Jul-17 23:27 
GeneralRe: Of Code and Comments Pin
I.explore.code2-Jul-17 1:01
MemberI.explore.code2-Jul-17 1:01 
GeneralRe: Of Code and Comments Pin
maze327-Apr-18 4:52
professionalmaze327-Apr-18 4:52 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.