- 0
How do you comment?
-
Recently Browsing 0 members
- No registered users viewing this page.
-
Similar Content
-
- 0 replies
- 3 views
-
- 53 replies
- 827 views
-
EA's excuse for paywalls in Battlefront II is Reddit's most hated comment 1 2
By Usama Jawad96,
- star wars
- star wars battlefront 2
- (and 14 more)
- 31 replies
- 701 views
-
- 6 replies
- 1,231 views
-
- 8 replies
- 1,112 views
-
Question
Karl L.
I know that commenting is a huge debate in programming. I was reading this article on Ars Technica, which is not primarily about commenting, but noticed that the person asking the question noted that he doesn't comment his code because he believes it is self-evident. However, most professional software development firms require commenting of some sort. So what is your personal opinion on commenting your code? Do you comment a lot, not at all, or somewhere inbetween? And, most importantly, why do you take that position?
As I have become a more experienced developer I have developed my own style. By most programmer's standards I believe that I comment quite a bit. I have a couple snipets of my code below, with the full source code for the class attached. (Note: The spacing is slightly screwed up. Not my fault. I blame Neowin's post editor.)
/*
Search for files directories.
Callback:
Every time a matching file or directory is found, SearchCallback() is called.
If it is not overridden, it will save the found files to internal storage, which can be accessed by calling GetFoundFiles() after this function returns.
64-bit Note:
If this function is being run from a 32-bit program on 64-bit Windows you might need to call Wow64DisableWow64FsRedirection() first to allow searching 64-bit paths.
If you use the aforementioned function, don't forget to call Wow64RevertWow64FsRedirection() after it completes to revert the setting!
MSDN Documentation: http://msdn.microsoft.com/en-us/library/aa365743.aspx
Side Effects:
Be advised: If you are using the default implementation of SearchCallback(),
the vector GetFoundFiles() returns is reset (cleared) every time this function is called.
Arguments:
File [in] Directory path to search.
If you supply a file we WILL return with an error!
Search [in] [optional] Find files and directories matching this search string.
Wild characters '*' (any number of characters) and '?' (only one character) are supported.
If the parameter is left blank everything we find will be processed!
Case [in] [optional] Is the search string case sensitive?
This paramter is ignored if Search is "" or "*".
Hidden [in] [optional] Should the search include hidden files and directories?
Recurse [in] [optional] Depth to enumerate the search path.
0 Enumerate the entire path.
1 Enumerate only the base directory.
2 Enumerate the base directory and any directories it contains.
3+ Enumerate all directories up to the designated level.
Return Value:
true We found at least one file or directory matching the search parameters.
flase Nothing was found matching the search parameters.
Are you sure we have permission to access the path?
*/
bool xFileSystem::Search( const std::string File, std::string Search, bool Case, bool Hidden, unsigned int Recurse )
{
//
// Check for trouble.
//
if( !this->IsDir( File ) ) return false; // We can only search directories!
if( Search.empty() ) Search = "*"; // If the search string does not exist, search for all files.
this->FoundFiles.clear(); // Clear our found files vector.
//
// Search the source directory.
//
xDirIt Handle( File, true, Hidden, Recurse ); // Handle for iterating the directory tree.
while( Handle.It() )
{
if( this->Abort ) return false;
// Strip the full directory path.
const char * FileIt = Handle.FileName; // Pointer to the file name that we will iterate through.
const char * LastGood = Handle.FileName; // Last known valid directory path.
while( *FileIt )
{
LastGood = FileIt;
while( *FileIt && *FileIt != '\\' ) FileIt++;
if( *FileIt ) FileIt++; // We don't actually want the '\\' character itself.
};
// Pass on the file information if the file name matches our search criteria.
if( this->WildCmp( Search.c_str(), LastGood, Case ) ) this->SearchCallback( Handle.FileName, Handle.FileAttrib );
};
return true; // Assume that everything ran successfully.
}
[/CODE]
What is your opinion on my commenting? Which category do I fall into, from your perspective.
xfs_1_3_1.zip
Link to comment
Share on other sites
18 answers to this question
Recommended Posts