I was sure a few months ago there was a gem that made sure you've commented every single line of code. Or at least every single action. If you hadn't, it brought your attention to it after you'd run some sort of rake task.
Can't remember for the life of me what it was called.
But is it a good idea to comment every single line of code? I say yes, it solidifies your knowledge, gives you a last change to catch bugs/security holes and eases future development.
However, projects in github and really sparsely commented. Personally, I need to comment most lines before I start to realise what a piece of code does. Is this not the case for most? Do comments just trip the code ninjas up?
Commenting every single line of code is a horrible idea:
It's noisy and obfuscates the source
It becomes out of date trivially easily
Things to comment:
Tricky and/or hacky code
Complicated algorithms
Why something is doing what it's doing
Those comments should almost always live at the method level.
If a code block needs a comment it should probably be a method
If a line of code needs a comment it should probably be refactored
Code should speak for itself as much as possible. Appropriate naming goes a long way to eliminating the need for wads of commenting. Some documentation may absolutely be necessary, but in the case of large structural comments, it may make more sense to keep it out of the code, and in your wiki.
No, it's not a good idea to comment every line of code. A lot of code is self-explanatory. In fact, you should strive to make your code self-explanatory.
For example, you would never want to comment the following:
sum = 1 + 3
You should save your comments for things that need explaining.
What I think you mean is a gem that enforces proper documentation. Documentation is a comment that explains the purpose of a method or class, as well as details its parameters and return values.
Regarding the gem you're thinking of, it may be rubocop.
Related
I've been reading Gene I Sher's Handbook to neuroevolution through Erlang and trying to replicate all the experiments described there.
And it all worked, until I came to chapter 19, which read
Having set everything up, we execute the benchmark for every noted experimental setup, and run it to completion. To do this, we simply modify the constraints used in our benchmarker module, and then execute benchmarker:start(Experiment_Name), for every of our experimental setups.
There are 14 experiments altogether, named:
1. [SlidingWindow5]2. [SlidingWindow10]3. [SlidingWindow20] 4. [SlidingWindow50]5. [SlidingWindow100]
and
1. [ChartPlane5X10]2. [ChartPlane5X20]3. [ChartPlane10X10]4. [ChartPlane10X20]5. [ChartPlane20X10]6. [ChartPlane20X20]7. [ChartPlane50X10]8. [ChartPlane50X20]9. [ChartPlane100x10]
Just starting a polis and running benchmarker:start(SlidingWindow5). in an erlang shell results in * 1: variable 'SlidingWindow5' is unbound.
I'm probably being obtuse and not doing something obvious, but I really wish to understand which arguments to pass to the benchmarker:start().
Reading the source code didn't help so far.
I think that reading the whole book is not necessary to figure out how to make this particular piece of code work.
All right. I needed to use an all-lowercase name: benchmarker:start(slidingwindow5)..
This answer is correct, but inconclusive; it gives the solution but does not explain why the solution is as it is from an Erlang perspective. Please don't upvote it until it does.
After googling a bit it seems there is no multi-line comment support in Erlang, is this really the case?
And if so, why?
I know some editors support commenting out regions (adding % first on every line of the region) but i don't really want to pick editor based on this.
It's simple. Use preprocessor:
-ifdef(comment).
Something to comment
You can add text or
function(Declaration) ->
...
Which will removed from file
-endif.
There are no multi-line comments in Erlang.
In general, I haven't found this to be a big deal: I use templates for gen_server and supervisor and a general template for other modules, and all of these include the boilerplate top doc blocks. I get some template support from my editor (Emacs) but you could be editor-agnostic and just write some templates and copy them to any new modules you want.
The biggest use of multi-line comments other than documentation is to comment-out a big chunk of code. Since your Erlang code should generally be small functions, you can just comment out the function call, which is a one-line comment.
I've got MMM-mode set up to edit .html.erb files, but indentation does not work in the ruby sections, and all the different electric behaviours of ruby-mode do the wrong thing. I've changed this sub-mode from ruby-moode to fundamental-mode, and it works much better.
I want to still use ruby-mode's font-locking though, is this possible/easy? Any hints on where to start.
Elisp is comfortable to me, but I don't have too much time right now to dig too deeply myself. Hopefully someone will have a snippet?
I see you haven't yet found an answer. Dunno whether it will be better for this, but you might consider using MuMaMo instead of MMM.
To answer the question, you would define a major mode deriving from fundamental-mode, and in its body just copy the font-lock-related lines from the ruby-mode definition body, the ones setting font-lock- variables and also syntax-propertize-function. Naturally , you need to (require 'ruby-mode) somewhere.
But for .html.erb files I can now recommend using mmm-erb, which was not available when this question was asked.
I've been learning Ruby/Rails with vim. Tim Pope's rails.vim seems like a really good tool to traverse files with, but I keep getting these pesky "E345 can't find file in path" errors. I'm not vim expert yet, so the solution isn't obvious. Additionally, I've tried this and it doesn't apply to my problem.
As an example of the problem. I have a method format_name defined in app/helpers/application_helper.rb and it is used in app/helpers/messages_helper.rb. Within the latter file I put my cursor over the usage of format_name and then hit gf and I get that error. Similar disfunction with commands like ]f and [f
However, it works sometimes. I was able to gf from user to the app/models/user.rb
Ideas?
I think that is a limitation of rails.vim. It does not support “finding” bare methods. Supporting something like that would require one of the following:
an exhaustive search of all the source files for each “find” request
(which could be expensive with large projects),
“dumb” indexing of method names
(e.g. Exuberant Ctags and gControl-]; see :help g_CTRL-]), or
smart enough parsing of the code to make a good guess where the method might be defined
(which is hard to do properly).
If you know where the method is, you can extend many of the navigation commands with a method name:
:Rhelper application#format_name
But, you do not have to type all of that in. Assuming the cursor is on format_name you can probably just type:RhTabspaceappTab#Control-R Control-W (see :help c_CTRL-R_CTRL-W).
I just caught myself doing something I do a lot, and wanted to generalize it, express it, share it and see who else is following this general practice, to find some other example situations where it might be relevant.
The general practice is getting something wrong first, on purpose, to establish that everything else is right before undertaking the current task.
What I was trying to do, specifically, was to find examples in our code base where the dojo TextArea widget was used. I knew (because I had it in front of me - existence proof) that the TextBox widget was present in at least one file. So I looked first for what I knew was there:
grep -r digit.form.TextBox | grep -v
svn
This wasn't right - I had made a common (for me) mistake of leaving off the star, so I fixed that:
grep -r digit.form.TextBox * | grep
-v svn
which found no results! Quick comparison with the file I was looking at showed me I had misspelled "dijit":
grep -r dijit.form.TextBox * | grep
-v svn
And now I got results. Cool; doing it wrong first on purpose meant my query was correct except for looking for the wrong thing, so now I could construct the right query:
grep -r dijit.form.TextArea * | grep
-v svn
and be confident that when it gave me no results, it was because there are no such files, and not because I had malformed the query.
I'll add three other examples as answers; please add any others you're aware of.
TDD
The red-green-refactor cycle of test-driven development may be the archetype of this practice. With red, demonstrate that the functionality doesn't exist; then make it exist and demonstrate that you've done so by witnessing the green bar.
http://support.microsoft.com/kb/275085
This VBA routine turns off the "subdatasheets" property for every table in your MS Access database. The user is instructed to make sure error-handling is set to "Break only on unhandled errors." The routine identifies tables needing the fix by the error that is thrown. I'm not sure this precisely fits your question, but it's always interesting to me that the error is being used in a non-error way.
Here's an example from VBA:
I also use camel case when I Dim my variables. ThisIsAnExampleOfCamelCase. As soon as I exit the VBA code line if Access doesn't change the lower case variable to camel case then I know I've got a typo. [OR, Option Explicit isn't set, which is the post topic.]
I also use this trick, several times an hour at least.
arrange - assert - act - assert
I sometimes like, in my tests, to add a counter-assertion before the action to show that the action is actually responsible for producing the desired outcome demonstrated by the concluding assertion.
When in doubt of my spelling, and of my editor's spell-checking
We use many editors. Many of them highlight misspelled words as I type them - some do not. I rely on automatic spell checking, but I can't always remember whether the editor of the moment has that feature. So I'll enter, say, "circuitx" and hit space. If it highlights, I'll back up over the space and the "x" and type another space - and learn that I spelled circuit correctly - but if it doesn't, I'll copy the word and paste it into a known spell-checker to see whether I did.
I'm not sure it's the best way to act, as it does not prevent you from mispelling the final command, for example typing "TestArea" or something like that instead of "TextArea" (your finger just have to slip a little for such a mistake).
IMHO the best way is to run your "final" command, but on two sample files first : one containing the requested text, another that doesn't.
In other words, instead of running a "similar" command, run the real one, but over "similar" data.
(Not sure if this would be a good idea to try for real!)
For example, you might give the system to the users for testing and tell them the password to get started is "Apple".
You know the users are fully up and ready to test (everything is installed and connections to databases working) when they contact you and say the password doesn't work (it's actually "Orange").