method for differentiating informative comments from commented out code
There is no automated commented-code cleansing. There necessarily must always be a man in the middle. A regex or parser can at best identify only "maybe". As pointed out in this thread the context must be understood.
The ideal is never to have to ask the question in the first place. ...
Yes, I think so.
A compiler parses input (text) in one language and outputs code in another language. It generally requires a parser, some intermediate representation, and a (code) generator. There may be optimization phases that analyze the intermediate representation for possible efficiency improvements. In some sense a compiler is a big ...
I have been using the second option, a JSON object, for a long time, but have never really been happy with it. At first I was constructing the JSON object manually. That proved to be troublesome as it is easy to screw up the syntax. so I wrote a helper to programmatically create data-options.
That worked well as far as creating valid JSON is concerned, but ...
Here's why you should use function:
The signaling is clear and concise. This is far more beneficial than any of the edge-case hoisting concerns that are listed in the other answer.
You actually want hoisting within modules because as you can see from the code below, the const declaration of tryDoTheThing fail silently and won't be caught until you try to ...
Probably gonna get shot down in flames here by the local pedant but:
Is there a more specific name to the act of writing code to write code
In very broad terms, yes - compilation or interpretation. Take the raw source code and change it into something else be that intermediate language, machine code or whatever.
Underpinning these are some tools called ...
Based on the description of what you want to do, I would recommend try a template engine before trying to do a full-fledged code-generation exercise. There are various ones available for Python. Jinja is used by Flask so you've already got it in your environment.
Simple, at least for me - and in C/C++. Comments enclosed in /* */ are informative. Test code that is temporarily removed is commented out with leading //.
And there is good reason to leave test code in the file but commented out, at least in the sort of work I do. Sooner or later someone will want a change made, which will need that code. Uncommenting a ...
Other answers have covered variations on the "don't comment out code" theme. But sometimes you do still want it around for reference.
If you genuinely need the code to stay around, a better solution is to surround the code with "#if 0 ... #endif", ideally with a comment to say why. This is the recommended strategy from various coding standards, including ...
I use preprocessor directives to remove code, not comments at all:
This makes a very easy thing to search for, and my syntax highlighter treats it as a comment. I can even collapse it into a single line: #if FALSE(...)
You can expand on that idea to have several options:
#if OPTION == 0
If you use an editor with a compiler running in the background (like Xcode and Clang), you can just try to compile the text of the comment. For example”a concise description” gives errors, “b = false;” doesn’t. You could then use different syntax highlighting.
A simpler method would be an IDE plugin that uses some heuristics, like multiple words in a row ...
I agree with the answer stating that old code should be removed rather than commented out where possible, however I have observed a convention for those few occasions when commented-out code is needed.
(My basis is C# but this can be applied to any C-syntax language eg java)
// An explanatory comment has a space between the comment marker and the content.
Adding to @RobertHarvey's excellent answer I believe there is only one legitimate reason I've ever encountered for saving commented code to source control, even temporarily: in case of non-obvious replacement code which should not or cannot be used right now for some reason. Even then most of the comment should be the explanation, not the replacement code. ...
I am interpreting the question different still, thinking you want to find commented out code.
C-style code is bound to have semi-colons in it while comment is unlikely to have semi-colons in it. So for single line commented-out code you could use this regular expression:
For multi-line commented-out code it could be
Hmm, I read this question slightly differently from Robert who correctly asserts that commented out code should be removed.
If, however, you are looking for a convention to mark code for later removal, an old favorite of mine is:
//b = false; //TODO: remove
Some IDE's flag //TODO: comments or can be taught to. If not, it's usually a searchable string. ...
There is a very simple solution to this: remove the commented-out code.
Really, there are only two good reasons to comment out code: to test something/make a fix, or to save code you might use later. If you're testing or fixing something, remove the commented out code as soon as you're done with the test or fix. If you're saving code you might use later, ...
If you follow Bob Martin's ''clean code'', then you might prefer option 2 (as in @David Arno and @casablanca.) Indeed,
One function argument is better than two
Simple well-named functions are better than complicated, vaguely named
Each function should do one and only one thing (ie, single responsibility principle at the basic level)
There is no right answer to this. In a general sense, you actually have three options:
Add an optional parameter,
Add a second function with a different name,
Add a second function with the same name, ie overload the function.
I'd choose option 2 for the following reasons:
A separately named method reveals the intention better than a boolean parameter that you need to look up to understand what it does.
Since you're not modifying any existing behaviour but simply doing something extra at the end, there isn't a good reason to change the original method to take an additional ...