Hi I have like 50 pages of code that I should write comments to it ... Can you guys show me the best way. I meant I need you to write me a sample ... the comments should contain nearly everything (classes, constructors, attribute, methods, events, functions)
相关问题
- Using XPath to access comments a flat hierachy
- should I write more descriptive function names or
- Python Encoding Comment Format
- How to increase mysql table comments length?
- How to ignore unassigned new in ReSharper?
You should not spend time writing documentation now, you should refactor this code. The design is not correct from a class-structure perspective. Your code should be structured as much as possible so that a class has a single responsibility it tries to achieve, and have a corresponding name.
Your Form1 (bad name, b.t.w.) does too much. It should ask other objects to help it. You might want to introduce a Tool class, which knows which label text and cursor are appropriate. You might want to use inheritance for the different shapes to do the drawing in a shape-specific way. In that way, your Form1 only has to delegate to the current tool.
With better structure you can reduce the amount of documentation you have to write. You might want to look up CRC-cards.
I recommend you to use XML comments in visual studio. Doing that you also can automatically generate documentation for your code, also other developers can see which method does what through intellisense.
http://www.winnershtriangle.com/w/Articles.XMLCommentsInCSharp.asp
http://msdn.microsoft.com/en-us/magazine/cc302121.aspx
Good comments will document intent, not function.
It's largely useless to comment assignments with "assign x to y" or similar.
It's much better to comment the code with a higher-level view of what the code aims to ultimately achieve, with pre- and post- conditions. You need to comment on (say) peculiar implementations or checks that are necessary yet counter-intuitive, and possibly reference specification documents etc.
If you've got to comment 50 pages of code, I suspect you're doing this at the wrong stage of your project. I tend to comment a class or method's intent with pre/post conditions prior to writing it. It's a form of mini-specification.
Don't comment what is obvious like
or
There might be a good idea to explain WHY a certain code line is there. For example explain why
Needs to be invalidated.
The basic idea is: add extra information with comments and use them for explanations, don't create redundancy and duplication.
EDIT:
You might also want to explain why each item in the toolbar needs to be unchecked here:
because is not obvious from the name of the event handler which button is clicked in order to understand why all buttons are unchecked.
A good comment would be something like:
I actually just wrote a blog post on this subject. Bear in mind that it is 100% possible (but perhaps not preferable) for code to contain no comments and be perfectly readable.