CodeSOD: Commentary

"Include descriptive comments for each method," isn't bad advice. I mean, ideally, the method name and parameters would be descriptive enough that you don't need to add lots of comments, but more comments is rarely going to hurt things. Unfortunately, "include descriptive comments" usually decays into "include comments". And that's how we get piles of code like this one, from Patrick:

// // Function name : CZiArecaRaidController::ReadAllRaidsetInfo// Machine : w7gre7// Environment : Visual Studio .Net 2008// doxygen : /// \fn CZiArecaRaidController::ReadAllRaidsetInfo(BSTR ContextInfo, IZiArecaDataCollection *pRaidsetInfoCollection, IZiArecaDataCollection *pVolumesetInfoCollection, IZiArecaDataCollection *pPhysicalDriveInfoCollection)/// \brief/// \details/// \paramContextInfo/// \param*pRaidsetInfoCollection/// \param*pVolumesetInfoCollection/// \param*pPhysicalDriveInfoCollection/// \returnSTDMETHODIMP /// \author(redacted)/// \date24.01.2011 09:59:10//STDMETHODIMP CZiArecaRaidController::ReadAllRaidsetInfo(BSTR ContextInfo, IZiArecaDataCollection **pRaidsetInfoCollection, IZiArecaDataCollection **pVolumesetInfoCollection, IZiArecaDataCollection **pPhysicalDriveInfoCollection){// ...}// // Function name : CZiArecaRaidController::GetArecaErrorMessage// Description : // Return type : string // Argument : ARC_STATUS stat// Author : (redacted)// Machine : Lapgre5// Environment : Visual Studio .Net 2005// Date/Time : 05.06.2007 15:24:53//string CZiArecaRaidController::GetArecaErrorMessage(ARC_STATUS stat){// ...}

This is the secret sauce of bad documentation: just repeat information already in the code, include information that absolutely doesn't need to be there, and make the whole thing take up more space than the code itself. The only way to make this documentation worse is to make it wrong.

It's the useless information which mystifies me. While knowing what environment was used to build the code is useful, why tag that onto individual methods? Why track which machine made the change? Why do source control by comment when the team was already using Subversion?

There is one thing that the documentation includes, though, that's useful to us. Sometime between 2007 and 2011 they added Doxygen to their toolchain. Perhaps between 2011 and 2022 they've also added meaningful documentation which would make Doxygen useful, but probably not.

[Advertisement] BuildMaster allows you to create a self-service release management platform that allows different teams to manage their applications. Explore how!