Consider a program which has a configuration file,
but the configuration file format does not have provisions for comments.
Maybe the program has a “list of authorized users”, where each line
takes the form
allow x or deny x,
where x is a group or user.
For example, suppose we have access_list that goes like this:
allow payroll_department deny alice allow personnel_department allow bob
This is the sort of file that can really use comments because people are going to want to know things like “Why does Bob have access?”
One way of doing this is to embed the comments in the configuration file in a way that has no net effect. You can do this to add separator lines, too.
deny !____________________________________________________________ allow payroll_department deny !alice_is_an_intern_and_does_not_need_access_to_this_database deny alice deny !____________________________________________________________ allow personnel_department deny !____________________________________________________________ deny !temporary_access_for_auditor deny !see_service_request_31415 deny !access_expires_on_2001_12_31 allow bob
Assuming that you don’t have any users whose names begin with
an exclamation point,
the extra deny !... lines have no effect:
They tell the system to deny access to a nonexistent user.
Sometimes finding the format of a line that has no effect can take some creativity. For example, if you have a firewall configuration file, you might use URLs that correspond to no valid site.
allow nobody http://example.com/PAYROLL_DEPARTMENT/-------------------- allow alice http://contoso.com/payroll/ allow nobody http://example.com/PURCHASING_DEPARTMENT/----------------- allow bob http://contoso.com/purchasing/ allow nobody http://example.com/SPECIAL_REQUEST/----------------------- allow ceo https://www.youtube.com/
Of course, these extra lines create work for the program,
since it will sit there evaluating rules that will never apply.
You may have to craft them in a way so that they have minimum cost.
In the example above,
we assigned the comments to a user called
nobody which presumably will never try to access the Internet.
We definitely didn’t want to write the comment like
allow * http://example.com/PAYROLL_DEPARTMENT/-------------------------
because that would evaluate the dummy rule for every user.
If you are willing to add a layer of process,
you can tell everybody to stop editing the configuration files directly
and instead edit an alternate file that gets preprocessed into a
configuration file.
For example, we might have
access_list.commented that goes
////////////////////////////////////////////////////////////////// allow payroll_deparment deny alice // payroll intern does not need access to this database. ////////////////////////////////////////////////////////////////// allow personnel_department ////////////////////////////////////////////////////////////////// allow bob // Temporary access for auditor, see SR 31415. Expires 2001/12/31.
Everybody agrees to edit the access_list.commented file,
and after each edit they run a script that sends the file through
the C++ preprocessor and puts the result in the
access_list file.
By using the C++ preprocessor, you enable features like
#include directives and
#define macros.
0 comments