[webkit-dev] coding style and comments

[Maciej Stachowiak]

On Jan 27, 2011, at 4:38 PM, Dirk Pranke wrote:

> I agree with all of the sentiments below, except for possibly one or two cases.
> 
> Namely, sometimes you write code where the "what" is not obvious. In
> that situation, it may not be possible to change the code to make it
> more obvious, because you are bound by contract. For example, suppose
> you are implementing an interface with a method called sort(). The
> fact that you choose a quicksort or a mergesort is a useful one-line
> comment, and in my opinion is probably better than just wrapping a
> method called quicksort() and hoping it gets inlined away.

I ran into this exact situation. I wanted to add a sort function that doesn't copy, only swaps. It happens that heapsort is such an algorithm. I named the public interface nonCopyingSort, made it call a function named heapSort, and wrote a comment explaining why heapSort is an appropriate implementation for nonCopyingSort:

http://trac.webkit.org/browser/trunk/Source/JavaScriptCore/wtf/NonCopyingSort.h

template<typename RandomAccessIterator, typename Predicate>
inline void nonCopyingSort(RandomAccessIterator start, RandomAccessIterator end, Predicate compareLess)
{
    // heapsort happens to use only swaps, not copies, but the essential thing about
    // this function is the fact that it does not copy, not the specific algorithm
    heapSort(start, end, compareLess);
}

Inlining works. IMO it's always better to use a well-named function to document what your code does than a comment. In this case I did it even though I also had a comment explaining why the function uses heapsort.

> 
> A slight variant of this is that you may be learning or
> reverse-engineering code where the "what" is not clear (perhaps
> because it was poorly rewritten). In the longer-term, ideally you'd
> clean up the code, but in the short term it might be useful to capture
> the "what" in comments until you can safely refactor things and delete
> the comments.

I would prefer for people to refactor instead of adding explanatory comments.

In general, I agree with what Eric and Darin said about this topic.

Regards,
Maciej