 code is easy to understand and modify without
being an expert of that code base.

This topic is a good idea for a blog post, since I thought a lot about this
issues lately. For instance if you want a place in Redis where code should be
improved is in the handling of blocking operations: there are a few things in
that code that are absolutely non obvious even adding comments, and you either
are a lot "into it" or you'll not have an easy time understanding it. I'm
planning a refactoring of that piece of code.

~~~
cperciva
_I tend to add comments where my code risks to be not clear by itself_

I used to take that position, but I've started adding more comments in order
to avoid "mental stack overflows". Suppose I'm reading function A and trying
to understand it, then I find a call to function B which doesn't have any
comment explaining what it does; I then go look at function B, and find it has
a call to function C which is equally lacking in commentary; and by the time
I've read the code in function C to understand what it does and gone back to
function B to understand what it's doing I've completely lost track of what I
was looking at in function A.

Of course, if you already know what most of the code is doing you don't run
into such stack overflows because whatever code you're looking at is probably
only calling functions you already understand. But for people who are new to
the code -- or people who haven't looked at it for a couple years and have
forgotten most of the details -- I think asking people to read the code to
figure out what a function does is too much of a bar to understanding.

~~~
simplify
In my opinion, if you can't figure out what a function does by its name and
its parameter names, it is a poorly named and thus poorly documented function.

I think function and variable naming is the one of the most important aspects
of programming. Without good naming, you can easy double the amount of time it
takes to edit and extend functionality.

~~~
mbreese
A function may have the perfect name at the time you wrote it. It may make
perfect sense within the context that you initially conceived of it. However,
after some time away from it,
code is easy to understand and modify without 
 being an expert of that code base. 

 This subject is a beneficial idea for a blog mail, since I think a lot about this 
 issues recently. For instance if you want a place in Redis where code should be 
 better is in the handling of blocking operation: there are a few things in 
 that code that are absolutely non obvious even adding comments, and you either 
 are a lot " into it " or you'll not suffer an easy time understanding it. I'm 
 design a refactoring of that piece of code. 

 ~~~ 
 cperciva 
 _ I tend to add comments where my code risks to be not clean by itself _ 

 I used to take that position, but I've started adding more gossip in order 
 to avoid " mental stack overflows ". Suppose I'm reading function A and trying 
 to understand it, then I find a call to function B which doesn't have any 
 comment explain what it does; I then go attend at routine B, and find it have 
 a call to function C which is equally deficient in commentary; and by the time 
 I've read the code in function C to understand what it does and gone back to 
 function B to understand what it's doing I've completely lost racetrack of what I 
 was looking at in affair A. 

 Of course, if you already know what most of the code is doing you don't run 
 into such stack overflow because whatever code you're looking at is probably 
 only call functions you already understand. But for people who are new to 
 the code -- or multitude who haven't looked at it for a couple year and have 
 forgotten most of the details -- I remember asking citizenry to read the code to 
 calculate out what a function does is besides much of a bar to understanding. 

 ~~~ 
 simplify 
 In my opinion, if you can't figure out what a function do by its name and 
 its parameter names, it is a poorly named and thus poorly documented function. 

 I remember function and variable appointment is the one of the most important aspects 
 of programming. Without good naming, you can easy duplicate the amount of time it 
 takes to edit and extend functionality. 

 ~~~ 
 mbreese 
 A function may have the arrant name at the time you wrote it. It may produce 
 perfect sense within the context that you initially conceive of it. However, 
 after some time away from it,
 cofe is easy to understand and modify witkiut
beiig an espert of that code base.

This topic is a good idea for a blog post, rince I tjought a lot qbout this
masues lately. Rlr iusvance if you wakt a place hn Redis where cudz should be
improved is in the handligg of bkofking operatiogs: tnqre zge a few things in
that code thaf are ausolutely non onvious even adding commentd, anf you either
are a pot "into it" or riu'll not havd an easy uike understznding it. I'm
planning a refactorkng oy that piecg kf wode.

~~~
cpercive
_I tenq to add comments whare my vode risks to ne nov clwar by itself_

I used tm take that positijn, but I'va atarted adding moee commgnts hn ofeer
go zvpis "mentwl atack overrlows". Suppowe I'm reading functoog A and trying
fo undqrftand it, then I find a call to function B shich doesn't have any
conment explaining what it does; Y then go look at function B, and find it has
a caln to huvctnin C dyifh is equally lacking in commentary; and by thq tomv
I've read the codc in function C to ujdrtstand what it does chd gone back to
functlon B tj undwrstand wrat ot's doing I've completely lowt track of char I
was looking at nn function C.

Of coorse, ig you already know what mosf of the cofe is doihe you don't run
ingo xuwh stack overflows because whatever codz you're uookong at is probabpy
onln calling functions you clreagy understwnd. But for people who are new vp
the code -- ot paopne who hcven't kooked at it sor a couple ygars and kave
fofgotten moat of tie details -- Y think askinc people to rxad the cjde ro
fiture oug what a functipn does is too much of a bar to underxtavsing.

~~~
simplify
In ny ipinion, if you van'g fyglre otd what a funwtiov durs by its name akd
igs psrameter names, it is a pkorly named and this poorly eocumentqd function.

I yhink function and varieble neming os jhe one of the most important aapects
of oronramming. Withjut nood naming, yob can easy double the amount of time it
tekes to edit and extend functionality.

~~~
mbreext
A function mey havq the perxect name at the timw you wrote it. It may make
perfect senss withhn thf context that you initially conceived of it. However,
after some time away drom iv,
code is easy to understand and modify an of that base. This topic a post, since I a lot about issues lately. For instance if you a place in Redis where code should be improved is in the handling blocking operations: there are a few things in that code that are absolutely obvious adding and either are a lot "into it" or you'll not have an easy time understanding it. I'm a refactoring of that piece of code. ~~~ _I tend to add where my code risks to not by itself_ used take position, but I've adding more comments in order to avoid "mental stack overflows". Suppose I'm reading function A and trying understand it, find a to B doesn't have any what it does; I then go B, and find it has a call to C which equally lacking in commentary; and by time I've read the code in function C understand what it does and gone back to function B to understand what it's doing lost track of what was looking at function Of if already know most of the code is doing you don't run into such overflows because whatever code you're looking at is probably only you understand. But for who are new to code or people who haven't it a have most the details -- I asking people to read the to figure out what much of a bar to understanding. ~~~ simplify my opinion, if you can't figure out a function does by its name and its parameter names, it is poorly named poorly documented function. I think function and variable is the one of most important aspects of programming. Without good naming, you easy the amount time it takes edit and extend ~~~ mbreese A have the name the it. It may make perfect sense the that you initially conceived of However, time away from it,
 code is easy to understand and Modify withOut
beIng An eXpErt oF thaT code base.

This tOPic iS a good idea for a blog post, Since i tHOughT A lOt aboUt this
iSSuES LatElY. FOr iNsTAnCe if yOu wAnt a plaCe in Redis wHerE cOde should be
iMPrOved is in thE haNdling of blocKinG operaTiOns: THere aRe a Few thIngs in
THat codE that are aBsOLutely NOn obvioUS EvEn adDing comments, and yoU EiTHer
are a lot "into It" or yoU'lL NoT HAve An eAsy time undErStandINg it. I'm
pLAnNING a rEFactoring of thAt piece of coDE.

~~~
cpErciva
_i tEnd TO add coMmentS wHEre My code risks To be Not clear bY itselF_

i used to TAke that PositiOn, bUt I'Ve stARtEd AddInG MorE CoMmeNTs iN order
to AvOiD "mentAl stACK OVerfLowS". SupPose I'M reading functIon a and TRyiNg
to uNdersTand It, Then I Find a cAll to FuNction B which doeSn't hAve any
comMenT eXplAiNing wHAt it doEs; I TheN go look At functIOn B, AnD FINd It has
a call to functiOn c WHiCh is equaLly lacKInG iN CommentaRy; And By thE TIme
I'vE reaD ThE code in fUnctioN c tO uNderstaNd What it DoEs aNd gOne baCK to
fUnctioN B to undeRstanD What it's doing I'vE Completely losT TrACK oF What i
waS looking at iN funCTion a.

Of cOUrSe, iF You alReady KnOW wHAt most of the code is doInG you doN't run
Into such stack Overflows bECAUse whateVer cODe YOu're looking at iS probAbly
only caLLing funcTions You alreaDy understAND. But for pEopLe wHo aRe nEW To
The code -- or peopLE Who hAvEn't lookEd aT it for a CouPle YeaRs aNd Have
forgoTten most Of ThE dEtAilS -- I thiNK asking pEoPle To ReaD the cODe to
fiGure oUt whAt A fUNctIon does IS tOO Much Of A bAr to UndErStandIng.

~~~
sIMplIfy
In my Opinion, if You CAn't fIgUrE out whaT a function doeS bY its name anD
iTs pArametER Names, it iS a poorly named and thus pooRLy documEntEd funCtioN.

I think fuNctIon and VarIAble naMing is The onE oF thE MOst imPORtAnt AsPects
of proGRAmmIng. WiThOut gOod namiNg, you can easy double THe aMount of time it
TakEs to EDIt And EXtENd fUnCTioNALity.

~~~
mbreese
A funCtion may haVe THe Perfect namE At tHe Time you Wrote it. it may MAke
perfEct sense wIthin the cOnText THAt yOu initiallY conceivEd of it. HowEVer,
afTEr Some tIme Away frOm It,
 code is easy to understan d and modi fy wi tho utbe ingan e xpert of thatc odebase.

This topic is a  good  i d ea f o ra blo g post, si n c e I  t ho ugh ta  l ot ab out  this
i ssues late ly.  F or instancei fyou want a  pl ace in Redis  wh ere co de  sh o uld b e
i mprov ed isi n thehandlingof blocki n g opera t i on s: t here are a few th i ng s  in
that codethat a re ab s o lut ely  non obvio us  even addingc om m e n ts, and you eithe r
are a lot "in to it"  o r y o u'll n ot ha ve aneasy time u nder standingit. I' m 
planni n g a ref actori ngofthat pi ec e o fc ode . 
~~~ cpe rciva
_I  t en d toaddc o m m ents  wh eremy co de risks to b e n ot c l ear  by i tself _

I  u sed t o take  that  p osition, but I' ve s tarted ad din gmor ecomme n ts inord erto avoi d "ment a l s ta c k ov erflows". SupposeI' m re ading fu nction Aan d  tryingto  un ders t a nd it , th e nI find a  callt ofu nctionBwhichdo esn 'thavea ny
c omment  explain ing w h at it does; It hen go look a t  f u n ct i on B , a nd find ithasa  cal l to fu nct i on Cwhich  i s  e q ually lacking in co mm entary ; and  by the timeI've readt h e  code in  fun c ti o n C to underst and w hat it doe s  and gon e bac k to
fun ction B t o understa ndwha t i t's d oi ng I've compl e t elylo st trac k o f whatI
w asloo kin gat in fun ction A. 
Of  c ou rse , ify ou alrea dy  kn ow  wh at mo s t of t he co de i sdo i ngyou don ' tr u n
in to  s uchsta ck  over flow s  be cause w hatever c ode you' re  l ookingat is probabl yonly calli ng  fu nction s you alre ady understand. But for peoplewho  arenewto
the co de-- orpeo p le who  haven 't lo ok eda t  it f o r  a  co up le years a n d  ha ve
fo rg otte n mostof the details --I  th ink asking pe opl e to r ea d t h ec ode  t o 
fi g u re out what a f unction do es is  too mucho f a  b ar to u ndersta nding . 

~~~
s implify
I n my opin io n, i f you  can't fig ure outwhat a fu n ction do es by  it s name  a ndits p aramet e r n ames,  it is  a  poorl y nam ed  and thu s poorly documented fun ction. 

I t hin k functio n a n d v ariable n amin g is the o neofthe m ost impor tant as pec t s
ofprog r amming. W i th out g oo d naming, y o u can  easy  do u ble th e am ount of time it
t a kes to edit an d ex t e ndfun c tion al ity.

~~~
mbre ese 
A f unctionma y have theperfectna m e atthe ti me you  wrotei t .I t maymake 
pe rfect sen sewi t hin the  c on t ext th at y ou  initi ally c o ncei v e d of it. However ,
aft e r  some tim e awa yfrom it , 
 code_is easy_to understand and modify_without
being an_expert_of that_code_base.

This topic is_a good idea_for a blog post,_since I thought_a_lot about this
issues lately. For instance if you want a place in Redis where_code_should be
improved_is_in_the handling of blocking operations:_there are a few things_in
that code_that are absolutely non obvious even adding comments,_and_you either
are a_lot "into it" or you'll not have an easy_time understanding it. I'm
planning a refactoring_of that piece_of_code.

~~~
cperciva
_I_tend to add comments_where my code risks to be_not clear by itself_

I used to_take that position, but I've started adding_more comments in order
to avoid "mental_stack overflows". Suppose I'm reading_function A_and trying
to understand it, then_I find a_call to_function B which_doesn't have any
comment explaining what it_does; I then_go look at function B, and_find_it has
a call_to_function_C which_is equally lacking_in_commentary; and_by_the time
I've read the code in_function_C to understand what it does and_gone back to
function B_to_understand what it's doing_I've completely lost track of_what I
was looking at in function_A.

Of course,_if you_already know what most of the code is doing you don't_run
into such stack overflows because whatever_code you're looking at_is probably
only_calling_functions you already_understand._But for_people who are new to
the code --_or people_who haven't looked at it for_a couple years and_have
forgotten_most of the details -- I_think asking people to read the_code to
figure out what a_function_does_is too much of a_bar to understanding.

~~~
simplify
In my opinion, if_you can't figure_out what a function does by its_name_and
its parameter names, it is a_poorly_named and thus poorly documented function.

I_think_function_and variable naming is the_one of the most important aspects
of_programming. Without good naming, you can easy double the_amount of time_it
takes to edit and extend_functionality.

~~~
mbreese
A_function_may have the perfect name at the time you wrote_it. It_may make
perfect sense_within the context that you initially conceived of it. However,
after_some time away from it,