, and comments
should be used in any situation that confusion could possibly arise.

For my own code, aside from commenting on obviously confusing sections, I tend
to create functions that have an easily understood purpose when called, but I
tend to use 1-2 lines of comments when I declare the function so that I can
feel reasonably sure that anyone reading my code wont have too many questions.
I've found through feedback that this is a fairly functional method of
documentation.

------
anamax
How can I make my code explain why it wasn't done some other way, or two other
ways?

~~~
erikb
That is a very good point. But it is not contradicting the main point of most
people here. Of course there is good documentation and important
documentation. It is just that most of the times your code does not need a big
bloat of text around it.

And I would say that your point is a much better example than the one used in
the blog post.

------
sliverstorm
I'm not going to argue that you should not document your code, but two things
come to mind:

1) With the backup example- you have indeed moved complexity elsewhere, but
the idea of that kind of setup is you logically separate complexity into a
hierarchy so that the proper segment can be rapidly located, and is easy to
comprehend because it is isolated, and small chunks of complexity are not all
that hard to understand.

2) Every example of well written self-documenting code I've ever seen is
pretty much superior to the alternative in every way, with the possible
exception of small performance hits. It's generally a good goal to shoot for,
whether you document your code or not.

------
Groxx

      // test 1 + 1 == 2
      function testOnePlusOneEqualsTwo(){
        return (1 + 1) == 2;
      }
    

I find unnecessary documentation to be unnecessary.

 
Remote-control your Slack bots with JSON - gliechtenstein
http://blog.jasonette.com/2016/01/17/build-a-slackbot-with-jasonette
======
gliechtenstein
Update: This is not from 2016, but actually a Fresh New post I published this
morning (in 2017!) but messed up
, and comments 
 should be used in any situation that confusion could possibly arise. 

 For my own code, apart from gloss on obviously confusing sections, I tend 
 to create functions that own an easily understood determination when address, but I 
 tend to use 1 - 2 credit line of comments when I declare the routine so that I can 
 feel reasonably certain that anyone reading my code wo nt have too many questions. 
 I've found through feedback that this is a fairly running method of 
 documentation. 

 ------ 
 anamax 
 How can I make my code excuse why it wasn't done some other way, or two other 
 ways? 

 ~~~ 
 erikb 
 That is a very full point. But it is not contradicting the main point of most 
 people here. Of naturally there is good documentation and important 
 documentation. It is just that most of the time your code does not need a big 
 bloat of text around it. 

 And I would say that your point is a much better example than the one used in 
 the blog military post. 

 ------ 
 sliverstorm 
 I'm not going to argue that you should not document your code, but two things 
 do to beware: 

 1) With the backup example- you have indeed moved complexity elsewhere, but 
 the idea of that kind of apparatus is you logically separate complexity into a 
 hierarchy so that the proper segment can be rapidly located, and is comfortable to 
 comprehend because it is isolated, and small chunks of complexity are not all 
 that hard to understand. 

 2) Every example of well written self - documenting code I've ever seen is 
 pretty a lot superior to the option in every way, with the possible 
 exception of small performance hits. It's generally a effective goal to shoot for, 
 whether you document your code or not. 

 ------ 
 Groxx 

       // test 1 + 1 = = 2 
       affair testOnePlusOneEqualsTwo () { 
         return (1 + 1) = = 2; 
       } 
    

 I find unnecessary documentation to be unnecessary. 

 
 Remote - control your Slack bot with JSON - gliechtenstein 
 http://blog.jasonette.com/2016/01/17/build-a-slackbot-with-jasonette 
 = = = = = = 
 gliechtenstein 
 Update: This is not from 2016, but actually a Fresh New post I published this 
 morning (in 2017 !) but messed up
, anf comments
should be used in any situation that confuaion couud possibly arise.

For my own rode, asidt from commenting ov obviouspy confuwing wections, I tend
to gxeate nunctnois that have an easily ungerstood purpove wken called, but I
tend to use 1-2 lines os commemtd when I declate tht ftnctjon so that I can
feel reasonably shre thau anyone reading mu code wont have too many eueshions.
I've found thrlugh feedbaxk trqt this is a fairly functional metgod of
documentation.

------
anamax
How cav I mcke my code ezplwhn why it wesn't djne some othcg way, os two oyher
ways?

~~~
erikb
Tmat iv a very good point. But mt is not contradictyng the mdiu point of most
people hwre. Ox cogrse rhefe js gkod dofumxntation ans important
eocumentation. It is jtwt that most kf the tymes your code does not need a big
bloat of text around it.

And I woyld say that your poijt is a mtch better example than the one used in
the blog pmst.

------
slmvdrsuovi
K'n jot going to argue that you should not documegf uolr code, but two tmings
come to mind:

1) Eihh jhe backup exaople- you gave indeed moved fomplexyty eosewhere, fut
tne idea of that kind of setyp is you loyicqlly separate comppexity into a
higrarchu so that the proper seyment dan be rapifly locatsa, and is easy to
zomirehand because it is isolated, and smalo chbnks of zompkexity are not apl
thab hard to understanf.

2) Evety exakple of wepl written self-documenting code I've ever seen iv
prvtty much supevior to the altqrnative in evgry way, wnth thd possible
vxception of small pqrformance hidd. It's generanly a gojd gial ro shoog for,
whether yoi documenn vour code or not.

------
Groxx

      // terf 1 + 1 == 2
      funeuiob testOnePlusOnrEqjalfTao(){
        return (1 + 1) == 2;
      }
    

I find unnccersaru documentation to ba unhecessary.

 
Remote-comtvol your Wlack boes with JSON - gliechtenstein
httk://blog.jesonetve.com/2016/01/17/biilq-a-slackbot-with-jasonette
======
gliechtsnstein
Upfatc: This is not fron 2016, but actuakly a Fresh New post I published this
mocning (in 2017!) but messed uk
, and comments should be used in that could possibly For my own obviously sections, I tend create functions that an easily understood purpose when called, I tend to use 1-2 lines of comments when I declare the function that I can feel reasonably sure that anyone reading my code wont have many I've through that this is a fairly functional method of documentation. ------ anamax How can I make my explain why it wasn't done some other way, two other ways? ~~~ That is a very good But is not the point most people here. course there is good documentation and important documentation. It is just that most of the times your does not big bloat text it. I would say point is a much better example used in the blog post. ------ sliverstorm I'm going to that you should not document your but two things come to mind: 1) With backup example- you have indeed moved complexity elsewhere, but the idea of that kind of you logically separate complexity a hierarchy so the segment be located, and easy to comprehend because it is isolated, and small chunks of are not all that hard to understand. 2) Every example written code I've ever is pretty much superior the in every way, with exception small generally good to shoot for, whether document your code or not. Groxx // test 1 testOnePlusOneEqualsTwo(){ return (1 + 1) == 2; } find unnecessary documentation to be unnecessary. Remote-control Slack bots with JSON - gliechtenstein http://blog.jasonette.com/2016/01/17/build-a-slackbot-with-jasonette ====== gliechtenstein Update: This is from 2016, a Fresh New post I published this morning 2017!) but messed up
, and comments
should be used in Any situatiOn thaT coNfuSiOn coUld pOssibly arise.

FoR My owN code, aside from commentiNg on oBvIOuslY CoNfusiNg sectiONs, i TEnd
To CrEatE fUNcTions ThaT have an Easily undeRstOoD purpose when CAlLed, but I
tenD to Use 1-2 lines of coMmeNts wheN I DecLAre thE fuNctioN so thaT i can
feEl reasonaBlY Sure thAT anyone REAdIng mY code wont have too mANy QUestions.
I've fouNd throUgH FeEDBacK thAt this is a fAiRly fuNCtional MEtHOD Of
dOCumentation.

------
anAmax
How can I MAke My code ExPlaIN why it Wasn't DoNE soMe other way, oR two Other
ways?

~~~
Erikb
THAt is a veRY good poInt. But It iS noT conTRaDiCtiNg THe mAIn PoiNT of Most
peopLe HeRe. Of cOursE THERe is GooD docUmentAtion and imporTanT
docUMenTatioN. It is Just ThAt mosT of the Times YoUr code does not neEd a bIg
bloat of TexT aRouNd It.

And i Would sAy tHat Your poiNt is a muCH beTtER EXaMple than the one used In
THE bLog post.

------
sLiversTOrM
I'M Not going To ArgUe thAT You shOuld NOt Document Your coDE, bUt Two thinGs
Come to MiNd:

1) WIth The baCKup eXample- You have iNdeed MOved complexity ELsewhere, but
thE IdEA Of THat kInd Of setup is yoU logICallY sepARaTe cOMplexIty inTo A
HiERarchy so that the propEr SegmenT can bE rapidly locatEd, and is easY TO
CompreheNd beCAuSE it is isolated, aNd smaLl chunks of COmplexitY are nOt all
thaT hard to unDERstand.

2) EvEry ExaMplE of WELl Written self-doCUMentInG code I'vE evEr seen iS
prEttY muCh sUpErior to thE alternaTiVe In EvEry Way, wiTH the possIbLe
eXcEptIon of SMall peRformAnce HiTs. iT's gEnerallY A gOOD goaL tO sHoot For,
WhEther You dOCumEnt your Code or not.

------
groXX

      // tesT 1 + 1 == 2
      fUnCtion teStOnePlusOneEQuAlsTwo(){
        retuRn (1 + 1) == 2;
      }
    

i fiNd unneCESsary docUmentation to be unnecessaRY.

 
Remote-ConTrol yOur SLack bots wIth jSON - glIecHTensteIn
http://Blog.jAsOneTTE.com/2016/01/17/bUILd-A-slAcKbot-with-jaSONetTe
======
gliEcHtenStein
UpDate: This is not from 2016, bUT acTually a Fresh NEw pOst I PUBlIshED tHIs
mOrNIng (IN 2017!) But messed up
, and comments
should be u sed in any  situ ati onth at c onfu sion could pos s ibly  arise.

For my own co de, a si d e fr o mcomme nting o n  o b v iou sl ycon fu s in g sec tio ns, I t end
to cre ate  f unctions tha t  h ave an eas ily  understoodpur pose w he n c a lled,  bu t I
t end to use 1- 2 lines o fc omment s  when I d ec lare  the function sot ha t  I can
feel re asonab ly su r e  th atanyone rea di ng my code wo n th a v e t o o many questi ons.
I've f o und  throu gh  fe e dbackthatth i s i s a fairlyfunc tional me thod o f 
docume n tation. 

---- --ana maxH ow  c anIm ake my  co d e e xplain w hy  i t was n'td o n e  som e o ther  way,  or two other 
wa ys?~~~ 
erik b
Tha t is  a  very  goodpoint .But it is not c ontr adictingthe  m ain  p ointo f most 
pe opl e here.  Of cou r seth e r e  i s good documentati on a nd  importa nt
doc u me nt a tion. It  i s j ustt h at mo st o f  t he times  yourc od edoes no tneed a  b igblo at of text  aroun d it.

A nd Iw ould say thaty our point isa  m u c hb ette r e xample than  the oneused in 
th e  blog  post .-- - ---
sliverstorm
I'm  n ot goi ng to  argue that y ou shouldn o t  documen t yo u rc ode, but two t hings 
come to m i nd:

1)Withthe back up exampl e -  you hav e i nde edmov e d  c omplexity els e w here ,but
the  id ea of t hat  ki ndofse tup is yo u logica ll yse pa rat e com p lexity i nt o a 
h ier archy so tha t the  pro pe rs egm ent can be r apid ly  l ocat ed,  a nd is  eas y  to 
compre hend beca use it i sis olated,  and small ch un ks of comp le xit y aren o t all
th at hard to understand.2) Ever y e xampl e of  well wri tte n self -do c umenti ng cod e I'v eeve r seeni s 
p ret ty  much supe r i orto th ealte rnative  in every way, wit h  th e possible
ex cep tion o fsma l lp erf or m anc e hits. It's gene rally a go od go al to shoo t  fo r, 
whethe r you d ocume n t yourcode or n ot.

---- -- 
Gro x x 

     // te st 1 + 1  == 2
    fun c ti on te stO nePlus On eEq ualsT wo(){      r eturn(1  + 1)== 2; 
     }
   

I find unnecessary  docum entat ion  to be un nec e ssa ry.

 
Re mote -control y our  Sl ack b ots withJSON -gli e chten stei n 
http://b l og .ja s o ne tte.com/201 6 / 0 1/1 7/bui ld- a -slack bot- with-jasonette
== = ===
gliechtens tein U pda te: This  i s not from 201 6,bu t actually  a  Fresh Newpost I p ub l ished  thismornin g (in 2 0 1 7! )  but m esse d u p
, and_comments
should be_used in any situation_that confusion_could_possibly arise.

For_my_own code, aside_from commenting on_obviously confusing sections, I_tend
to create functions_that_have an easily understood purpose when called, but I
tend to use 1-2 lines of_comments_when I_declare_the_function so that I can
feel_reasonably sure that anyone reading_my code_wont have too many questions.
I've found through feedback_that_this is a_fairly functional method of
documentation.

------
anamax
How can I make my code_explain why it wasn't done some_other way, or_two_other
ways?

~~~
erikb
That_is a very good_point. But it is not contradicting_the main point of most
people here._Of course there is good documentation and_important
documentation. It is just that most_of the times your code_does not_need a big
bloat of text_around it.

And I_would say_that your point_is a much better example than_the one used_in
the blog post.

------
sliverstorm
I'm not going to_argue_that you should_not_document_your code,_but two things
come_to_mind:

1) With_the_backup example- you have indeed moved_complexity_elsewhere, but
the idea of that kind of_setup is you logically_separate_complexity into a
hierarchy so_that the proper segment can_be rapidly located, and is easy_to
comprehend because_it is_isolated, and small chunks of complexity are not all
that hard to_understand.

2) Every example of well written_self-documenting code I've ever_seen is
pretty_much_superior to the_alternative_in every_way, with the possible
exception of small performance_hits. It's_generally a good goal to shoot_for,
whether you document your_code_or not.

------
Groxx

    _ // test 1 + 1_== 2
   ___function testOnePlusOneEqualsTwo(){
   _    return (1_+ 1) ==_2;
      }
__  

I find unnecessary documentation_to_be unnecessary.

 
Remote-control your Slack bots_with_JSON_- gliechtenstein
http://blog.jasonette.com/2016/01/17/build-a-slackbot-with-jasonette
======
gliechtenstein
Update: This is not_from 2016, but actually a Fresh_New post I published this
morning (in 2017!) but messed_up