On Wed, 7 Mar 2001, Rik van Riel wrote:
> I've taken today to write some documentation for
> include/linux/mm.h, as used in 2.4.x
Mostly good.
> + pgprot_t vm_page_prot; /* Access permissions of this VMA. */
But a lot of the comments are trivial = deadweight. Comments are best used
for the bits that are magical without them, which should be few.
> + struct page *next_hash; /* Next page sharing our hash bucket in
> + the pagecache hash table. */
Multiline comments at the end of the line are hard to maintain and highly
susceptible to tab damage.
> + atomic_t count; /* Usage count, see below. */
> + unsigned long flags; /* atomic flags, some possibly
> + updated asynchronously */
I'm sure there's a good reason why the flags aren't atomic_t but this
comment would make me suspect a bug. Comments that don't agree with code
are worse than no comments.
-- "Love the dolphins," she advised him. "Write by W.A.S.T.E.."- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
This archive was generated by hypermail 2b29 : Thu Mar 15 2001 - 21:00:08 EST