Style guideline
Maciej Piechotka
mostly on http://merbivore.com/contribute.html - however with a few
changes.
Please note that it should be guide only and the formatting of code
may follow (however it will make life easier if it will be from
beginning ok).
The current code is not formatted and I'm going to do some cleanup in
separate branch.
== Parentheses ==
Current state: As in merb around method definitions. In method calls
not necessary.
Proposed supplement: If a method change a state[1] it should have
parentheses. For example:
a = iterator.current
b = Something.new()
c = mock()
Motivation: It make visible if you can reuse the property or you have
to assign to variable if you want to have the same value.
[1] in visible way - not updating cache or other such things - of
which you cannot think as a 'property' or 'variable'
== Indent ==
Two-space as in merb and most of ruby
== Documentation ==
As in merb. Required
== Column width ==
As in standard terminal - 80
== Strings ==
Proposed supplement: If the string is dynamic - for example "#{abc}:
#{def}" it should be rounded by ". However otherwise it should be
rounded by '.
Motivation:
1. The ' are faster (at least I heard so - my benchmarks have varied
results)
2. They show if the string is dynamic or not
Please comment - especially the supplements. The good style guildeline
help reading but wrong limit the creation of code.
Regards
Alex Coles
<uzytk...@gmail.com> wrote:
>
> Some of the style guideline is being somehow formed. It is based
> mostly on http://merbivore.com/contribute.html - however with a few
> changes.
> Please note that it should be guide only and the formatting of code
> may follow (however it will make life easier if it will be from
> beginning ok).
I agree that the Merb guidelines are good and should form a basis for
our own code formatting guidelines.
> The current code is not formatted and I'm going to do some cleanup in
> separate branch.
Great. It would be good to start standardising the formatting of
what's in the repository. Its probably better if you do it on code
that you've written yourself (although I don't mind doing it either).
> == Parentheses ==
> Current state: As in merb around method definitions. In method calls
> not necessary.
>
> Proposed supplement: If a method change a state[1] it should have
> parentheses. For example:
> a = iterator.current
> b = Something.new()
> c = mock()
> Motivation: It make visible if you can reuse the property or you have
> to assign to variable if you want to have the same value.
>
> [1] in visible way - not updating cache or other such things - of
> which you cannot think as a 'property' or 'variable'
I agree, except for empty parentheses - which personally, I don't
like. I'd rather see Something.new than Something.new().
> == Indent ==
> Two-space as in merb and most of ruby
Yep. 2 spaces. NO Tabs.
See also below.
I would suggest 2 line breaks between method definitions (end... def)
as I think this is more readable, and also between long if, case,
statements, etc.
> == Documentation ==
> As in merb. Required
Merb (and also DataMapper) are moving to the YARD documentation
standard. I'd like to move to YARD as well. I converted a bunch of
docs from regular RDoc to YARD for the DM project, so I don't mind
taking this on.
> == Column width ==
> As in standard terminal - 80
Agreed. Also, a good idea to strip trailing whitespace. There is a
sake task that takes care of this automatically 'sake strip' :
www.datamapper.org/dm-dev.sake
Useful to keep whitespace consistent as there is no way (currently) of
ignoring whitespace differences when using GitHub's commit diff
view...
If using git rebase, a bunch of warnings are thrown when trailing
whitespace is encountered, so its a good idea to get rid of it.
> == Strings ==
> Proposed supplement: If the string is dynamic - for example "#{abc}:
> #{def}" it should be rounded by ". However otherwise it should be
> rounded by '.
> Motivation:
> 1. The ' are faster (at least I heard so - my benchmarks have varied
> results)
> 2. They show if the string is dynamic or not
Agreed. I am sometimes a little loose with this one, but I should
start to become more disciplined.. I don't know what the performance
impact is, but still its good to distinguish the two, I think.
> Please comment - especially the supplements. The good style guildeline
> help reading but wrong limit the creation of code.
Good idea. Maybe you could copy and paste this into the Wiki?
Alex
Maciej Piechotka
> On Thu, May 29, 2008 at 12:48 PM, Maciej Piechotka
>
>
> > The current code is not formatted and I'm going to do some cleanup in
> > separate branch.
>
> Great. It would be good to start standardising the formatting of
> what's in the repository. Its probably better if you do it on code
> that you've written yourself (although I don't mind doing it either).
>
repository
> > == Parentheses ==
> > Current state: As in merb around method definitions. In method calls
> > not necessary.
>
> > Proposed supplement: If a method change a state[1] it should have
> > parentheses. For example:
> > a = iterator.current
> > b = Something.new()
> > c = mock()
> > Motivation: It make visible if you can reuse the property or you have
> > to assign to variable if you want to have the same value.
>
> > [1] in visible way - not updating cache or other such things - of
> > which you cannot think as a 'property' or 'variable'
>
> I agree, except for empty parentheses - which personally, I don't
> like. I'd rather see Something.new than Something.new().
>
several times mock as a variable not method creating mock ;)
> > == Indent ==
def method(params)
# ...
end
# Documentation
def second_method(params)
#...
end
> as I think this is more readable, and also between long if, case,
> statements, etc.
>
short if can be separated if it means something different.
On the other hand not all instruction should be separated. For
example:
i = Net::Something.open(...)
while i.something
# ...
end
cache << i
can be in a one logical block (ok - in ruby it'll be rather:
cache << Net::Something.open(...) do |i|
# ...
end
but it was just an example ;) ).
> > == Documentation ==
> > As in merb. Required
>
> Merb (and also DataMapper) are moving to the YARD documentation
> standard. I'd like to move to YARD as well. I converted a bunch of
> docs from regular RDoc to YARD for the DM project, so I don't mind
> taking this on.
>
> > == Column width ==
> > As in standard terminal - 80
>
> Agreed. Also, a good idea to strip trailing whitespace. There is a
> sake task that takes care of this automatically 'sake strip' :www.datamapper.org/dm-dev.sake
>
> Useful to keep whitespace consistent as there is no way (currently) of
> ignoring whitespace differences when using GitHub's commit diff
> view...
>
> If using git rebase, a bunch of warnings are thrown when trailing
> whitespace is encountered, so its a good idea to get rid of it.
>
> > == Strings ==
> > Proposed supplement: If the string is dynamic - for example "#{abc}:
> > #{def}" it should be rounded by ". However otherwise it should be
> > rounded by '.
> > Motivation:
> > 1. The ' are faster (at least I heard so - my benchmarks have varied
> > results)
> > 2. They show if the string is dynamic or not
>
> Agreed. I am sometimes a little loose with this one, but I should
> start to become more disciplined.. I don't know what the performance
> impact is, but still its good to distinguish the two, I think.
>
parsed (if there is no dynamism in it). My benchmark (primitive - very
primitive):
require 'benchmark'
Benchmark.bm do |bm|
bm.report('The \' strings') {n.times {a = 'Test string'}}
bm.report('The " strings') {n.times {a = "Test string"}}
end
has shown that the '-strings to "-strings are 1:10 to 1.5:1 (where
1:10 means that the '-strings are 10 times faster).
> > Please comment - especially the supplements. The good style guildeline
> > help reading but wrong limit the creation of code.
>
> Good idea. Maybe you could copy and paste this into the Wiki?
>
mailing list. When we finish the thinking I'll add it to the wiki.
> Alex
Maciej
Alexander Coles
On May 29, 2008, at 5:11 PM, Maciej Piechotka wrote:
>
> I started cleanup branch. If you agree I may add it to the main
> repository
Of course, merge back into master when you feel its ready.
>> I agree, except for empty parentheses - which personally, I don't
>> like. I'd rather see Something.new than Something.new().
>>
>
> Well. I'm used to omit the empty parentheses as well. However I used
> several times mock as a variable not method creating mock ;)
Oh, I see. Well in this case, perhaps an exception could be made.
>>> == Indent ==
>> I would suggest 2 line breaks between method definitions (end... def)
>
> Like that:
>
> def method(params)
> # ...
> end
>
>
> # Documentation
> def second_method(params)
> #...
> end
Actually, I meant one blank line - or 2 \n
> I usually rather part the code on base of logical structure - and even
> short if can be separated if it means something different.
> On the other hand not all instruction should be separated. For
> example:
>
> i = Net::Something.open(...)
> while i.something
> # ...
> end
> cache << i
>
> can be in a one logical block (ok - in ruby it'll be rather:
>
> cache << Net::Something.open(...) do |i|
> # ...
> end
>
> but it was just an example ;) ).
Good example. I am a recent convert from Java, so I am getting used to
being able to write nice blocks like the the rewritten example :)
>>> == Strings ==
>
> Theoretically the '-strings are taken 'as-it' and in "-string are
> parsed (if there is no dynamism in it). My benchmark (primitive - very
> primitive):
> require 'benchmark'
>
> Benchmark.bm do |bm|
> bm.report('The \' strings') {n.times {a = 'Test string'}}
> bm.report('The " strings') {n.times {a = "Test string"}}
> end
>
> has shown that the '-strings to "-strings are 1:10 to 1.5:1 (where
> 1:10 means that the '-strings are 10 times faster).
Interesting benchmarks. That is something I wouldn't have thought of
looking into, but obviously makes a difference if you're doing a lot
of String manipulation.
> I wanted to post the wiki but since I added a few ideas I decided on
> mailing list. When we finish the thinking I'll add it to the wiki.
Yep, sure. I am fairly easy going on this -- esp. since you've already
done about 90% of the coding for 0.0.1!
Alex
Maciej Piechotka
> On May 29, 2008, at 5:11 PM, Maciej Piechotka wrote:
>
> >> I agree, except for empty parentheses - which personally, I don't
> >> like. I'd rather see Something.new than Something.new().
>
> > Well. I'm used to omit the empty parentheses as well. However I used
> > several times mock as a variable not method creating mock ;)
>
> Oh, I see. Well in this case, perhaps an exception could be made.
>
> >>> == Indent ==
> >> I would suggest 2 line breaks between method definitions (end... def)
>
> > Like that:
>
> > def method(params)
> > # ...
> > end
>
> > # Documentation
> > def second_method(params)
> > #...
> > end
>
> Actually, I meant one blank line - or 2 \n
>
without?
def method
# ...
end
# documentation
def documented_method
# ...
end
def undocumented_method
# ...
end
or
def method
# ...
end
# documentation
def documented_method
# ...
end
def undocumented_method
# ...
end
>
>
> > I usually rather part the code on base of logical structure - and even
> > short if can be separated if it means something different.
> > On the other hand not all instruction should be separated. For
> > example:
>
> > i = Net::Something.open(...)
> > while i.something
> > # ...
> > end
> > cache << i
>
> > can be in a one logical block (ok - in ruby it'll be rather:
>
> > cache << Net::Something.open(...) do |i|
> > # ...
> > end
>
> > but it was just an example ;) ).
>
> Good example. I am a recent convert from Java, so I am getting used to
> being able to write nice blocks like the the rewritten example :)
>
> >>> == Strings ==
>
> > Theoretically the '-strings are taken 'as-it' and in "-string are
> > parsed (if there is no dynamism in it). My benchmark (primitive - very
> > primitive):
> > require 'benchmark'
>
> > Benchmark.bm do |bm|
> > bm.report('The \' strings') {n.times {a = 'Test string'}}
> > bm.report('The " strings') {n.times {a = "Test string"}}
> > end
>
> > has shown that the '-strings to "-strings are 1:10 to 1.5:1 (where
> > 1:10 means that the '-strings are 10 times faster).
>
> Interesting benchmarks. That is something I wouldn't have thought of
> looking into, but obviously makes a difference if you're doing a lot
> of String manipulation.
>
manipulating code as web-app. But it creates a difference betwean
those two ;)
Regards
Maciej Piechotka
> Some of the style guideline is being somehow formed. It is based
the top.
I.e.
class Test
protected :test2
def test1
# ...
end
def test2
# ...
end
def test3
# ...
end
end
is preferred over
class Test
def test1
# ...
end
protected :test2
def test2
# ...
end
def test3
# ...
end
end
Regards
Maciej Piechotka
>
>
> > == Documentation ==
> > As in merb. Required
>
> Merb (and also DataMapper) are moving to the YARD documentation
> standard. I'd like to move to YARD as well. I converted a bunch of
> docs from regular RDoc to YARD for the DM project, so I don't mind
> taking this on.
>
handle few things (or I don't know how to force it to do it):
- Module defined in few files (i.e. methods of it)
- Inclusion only of one directory
Regards
Alexander Coles
No, unfortunately its not mature. There is a pretty big rewrite going
on at the moment (in the api_branches) section of YARD, but I don't
know how complete it is. Might be an idea to ask in the #yard channel?
Alex