Preferred Editor(s) (176)

87 Name: #!/usr/bin/anonymous : 2008-08-06 06:17 ID:9CP8PUFI

>>85

Visual Studio makes the XML trivial as it adds it for you, you only need to provide the content.

Comments are only limited by a persons ability to accurately describe the code. Its apparent that you have not used a mature API extensively. Take something like the .Net APIs. The Visual Studio object explorer displays the XML comments for the APIs (and any other well commented code you are using). This tool is invaluable as is intelligence which also gets its info from the XML comments.

Parameter names should be self evident, but they can't always be. If a function takes a path to a file name, and it has to be a fully qualified path do you name it "strPathName"? That doesn't tell you shit about it. Its obviously for a path, but is it a relative path or a fully qualified one or doesn't it matter? What if there are overloads that take other paths, do you have to get super descriptive? Do you name it "strFullyQualifiedPathNameToTheFileYouWantToWorkWith"? Or maybe I should just memorize the API's full documentation, that sure is reasonable.

Or would it work better if you name it "PathName" and a little tool-tip came up when you got to the point to enter the parameter in the IDE and it read "String: Fully qualified path to the file to work with." Think about that for a while.

>>86

/// <summary>
/// Summary of LoadXMLFromFile.
/// </summary>
/// <param name="FilePath">Description of FilePath parameter.</param>
public void LoadXMLFromFile(string FilePath)

That is a basic C# XML comment (that is autogenerated with me adding the text between the tags). If you find that hard to read or pushing the comment delimited 3 times to auto-gen the XML to hard to do, you might want to choose a different hobby.

Any good developer today should be able to view XML and understand it. But since you don't, I suppose you have a better idea for a markup language to use to give context and meaning to programming comments. You can't be a true badass programmer until you have dismissed, without a reason, the ideas that teams of computer scientists and computer engineers have put way more thought in to that you have.

Name: Link:
Leave these fields empty (spam trap):
More options...
Verification: