JAYATHEERTH K <jayatheerthkulkarni2005@xxxxxxxxx> writes: >> ... better to explain _why_ each change is made in the text that >> precedes the sample code. E.g. >> >> Add `#include "config.h"` because you want to use X and Y, >> and `#include "repository.h"` because you want to use Z. >> >> ... > In the latest patch version I've removed the comments, since we > already added a line above saying the user has to include > `repository.h` I don't think we need to go in depth into that, do let > me know if that is not the case, looking forward to any more feedback. It's your patch, after all. But if the reason why you added the comment was "this is a tutorial" as you said, I would imagine that it would help readers to say why a particular header is needed, when the tutorial text tells them that they need to add it. From a quick look at the patch, it seems that the updated text says what the change did (i.e. add a header), which is rather obvious in the sample code, without saying why the addition is necessary?
