3

When certain parts of code are unusual or unclear, common practice is to leave a comment explaining why it is so. However, sometimes a filesystem may have unusual configuration, such as a directory with 0477 privileges. Is there any convention for leaving comments about this?

I am writing a 'Developers Wiki' for the company as that would be the place for such things. However I would prefer something more standard if it exists and more accessible when, for instance, the next guys has to SSH in from home in the middle of the night and he might not think to check the wiki (or even have access to it).

dotancohen
  • 1,041

3 Answers3

6

Any place where your code expects an unusual configuration, have it explicitly check for that configuration and clearly explain the expectation in the appropriate error message / log file entry.

If Ops calls your guy at 2 am with

"TheApp crashed with a message 'error 2468: /rootdir/specialdir must have 0477 privileges'", then at least his SSH fix will be quick.

On a side note, if at all possible, try to avoid this situation. Standard/vanilla configurations are easier to maintain / harder to mess up.

Clarification: in addition to any documentation, also ensure the code "documents" the issue with explicit checks and error handling. The very first thing a person reads when there's a problem isn't the doc or the wiki, it's the error message.
Dan Pichelman
  • 13,813
3

In a project, it's typical to have a readme or a summary of the project, and in it, a quick description of the project structure is warranted. There, I think you could place an explanation for the permissions of the directories. If the developer should fail to check the wiki, hopefully they will think to check the readme.

Does that answer your question?

Neil
  • 22,750
  • The README file might be a good idea, thank you. I will wait a bit to see what other responses are suggested. – dotancohen Jun 18 '14 at 15:07
1

To add to @Neil's answer above, putting a readme file in the directory in question would also be very useful. 6 months (or 6 years) after the project is done, developers might not even know which project caused the change, to find the wiki/readme. Similar to comments in code, this puts the explanation right with the problem/outlier.

This solution also can help your SysAdmins help debug and correct the problem without even having to call you. These people won't have any idea which project is involved, but they will have the information right in front of them.

cdkMoose
  • 1,785
  • Meh, I'm of the opinion that if I were looking for information regarding the project structure, I wouldn't look for it in the folder in question. Also consider that I may not have access to the folder in question. Food for thought. :) – Neil Jun 18 '14 at 15:36
  • The problem is that the person looking for the information may have no idea what project to look at for the information. For a system that grows over time, this change could have been from many projects back. If nothing else, this readme file could point to the correct project documentation. – cdkMoose Jun 18 '14 at 15:55
  • That's true. If nothing else, it could just read, "Look in the d*** wiki." – Neil Jun 18 '14 at 15:57