[webkit-dev] coding style and comments
mjs at apple.com
Fri Jan 28 11:34:08 PST 2011
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:
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.
More information about the webkit-dev