Ch5 Knowing What to Comment

1.Comment the Flaws in Your Code

// Enforce limits on the Reply as stated in the Request,
// such as the number of items returned, or total byte size, etc.
var CleanReply = function (request,  reply)
{
/*    Marker Typical meaning
    TODO: Stuff I haven’t gotten around to yet
    FIXME: Known-broken code here
    HACK: Admittedly inelegant solution to a problem
    XXX: Danger! major problem here*/

}

TODO : 아직 하지 않은 일

FIXME:  오동작을 일으킨다고 알려진 코드

HAXK : 아름답지 않은 해결책

XXX: 위험! 여기 큰 문제가 있다.

TextMate : ESC

 

2.Comment on Your Constants

 

/// Make sure 'reply' meets the count/byte/etc. limits from the 'request'
var EnforceLimitsFromRequest = function (request,  reply)
{
    NUM_THREADS = 8     ;

    NUM_THREADS = 8 // as long as it's >= 2 * num_processors, that's good enough.

    // Impose a reasonable limit - no human can read that much anyway.
    var  MAX_RSS_SUBSCRIPTIONS = 1000;

    var image_quality = 0.72; // users thought 0.72 gave the best size/quality tradeoff

}

 

3.Don’t Comment Bad Names—Fix the Names Instead

 

void CleanReply(Request request, Reply reply); // comment for a function named CleanReply():

void EnforceLimitsFromRequest(Request request, Reply reply);
/*This function name is more “self-documenting.” A good name is better than a good comment
because it will be seen everywhere the function is used.
    

void DeleteRegistry(RegistryKey* key);

void ReleaseRegistryHandle(RegistryKey* key);

/*The name DeleteRegistry() sounds like a dangerous function (it deletes the registry?!). The
comment “This doesn’t modify the actual registry” is trying to clear up the confusion.
    Instead, we could use a more self-documenting name like:*/

 

4.Put Yourself in the Reader’s Shoes
*struct Recorder {
    vector<float> data;
...
    void Clear() {
        vector<float>().swap(data); // Huh? Why not just data.clear()?
    }
};

//it turns out that this is the only way to force a vector to
//truly relinquish its memory to the memory allocator

void Clear() {

    // Force vector to relinquish its memory (look up "STL swap trick")
    vector<float>().swap(data);
}
*};