Forums
Dec 21Commentary
by in CodeSOD on 2022-01-20"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
/// \param ContextInfo
/// \param *pRaidsetInfoCollection
/// \param *pVolumesetInfoCollection
/// \param *pPhysicalDriveInfoCollection
/// \return STDMETHODIMP
/// \author (redacted)
/// \date 24.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)
{
// ...
}