 fixing now (done by you of course).

With this process you reach many goals at once and make sure to not put in
resources that are not nessesarily needed. Also you can see that this process
is able to handle ugly code, situations where unit tests where forgotton to
write and basically many kinds of mistakes that coders do because they are
humans (error prone and lazy).

By the way, the same process also works for new feature requests.

------
j_baker
I grant that all code can't be self documenting. But you don't commit suicide
just because you're going to die at some point anyway. Instead, you try to
make your life as long and happy as possible.

Your highest priority should be to make your code self-documenting as
possible, even though that isn't always possible.

That said, the author does have a valid point in that public APIs do need
documentation. But I wouldn't go so far as to say that _every_ method (private
or not) needs documenting. Unnecessary comments and documentation should be
treated like any other kind of useless code. They should be removed.

------
Jach
Perhaps not, but I don't think inline documentation is often very useful
either and breaking code density is a jarring thing. External documentation
exists for a reason (even if it's just doxygen-izing your inline docs instead
of pointing people at the direct source), and I much prefer reading (and
writing) short READMEs, examples, or tutorials than digging through
implementation code if I'm interested in using something. And if I'm
integrating anything non-trivial I don't think little comments saying "/* *
executes the passed query string, not using prepared statements, throws
SQLException, returns nothing */ public static void executeSql(String query)
throws SQLException {" are useful or worth my time. Write comments when
something needs some explanation not clear from the context, save the academic
comment-everything documentation for enterprise busywork or academia.

~~~
beoba
I think you're mixing up inline documentation with api documentation.

For inline stuff where it's explaining a complex/dense lump of code, it's
useful to keep it as close to the original code as possible, so that if
somebody updates the code, they're more likely to see/update the comments as
fixing now (done by you of course). 

 With this procedure you strive many goals at once and make sure to not invest in 
 resources that are not nessesarily needed. besides you can see that this process 
 is able to handle surly code, situations where unit test where forgotton to 
 write and basically many kinds of mistake that programmer do because they are 
 humans (mistake prone and lazy). 

 By the way, the like process also works for raw feature requests. 

 ------ 
 j_baker 
 I concede that all code can't be self documenting. But you don't commit suicide 
 merely because you're going to die at some point anyway. Instead, you judge to 
 make your life as long and happy as possible. 

 Your high priority should be to make your code self - documenting as 
 possible, even though that isn't always possible. 

 That said, the author does have a valid point in that public APIs do need 
 software documentation. But I wouldn't move so far as to suppose that _ every _ method acting (private 
 or not) needs documenting. Unnecessary comments and documentation should be 
 treated like any other kind of useless code. They should be removed. 

 ------ 
 Jach 
 Perhaps not, but I don't remember inline documentation is often very useful 
 either and breaking code density is a jarring thing. External software documentation 
 exists for a reason (even if it's just doxygen - izing your inline docs instead 
 of pointing people at the lineal beginning), and I much prefer reading (and 
 writing) short READMEs, examples, or tutorials than digging through 
 execution code if I'm interested in use something. And if I'm 
 integrating anything non - trivial I don't intend little comment saying " / * * 
 executes the excrete query bowed stringed instrument, not using disposed statements, throws 
 SQLException, render nothing * / public static void executeSql(String question) 
 throws SQLException { " are useful or worth my time. Write comments when 
 something needs some explanation not clear from the context, save the academic 
 comment - everything documentation for enterprise busywork or academia. 

 ~~~ 
 beoba 
 I think you're blend up inline documentation with api documentation. 

 For inline material where it's explaining a complex / dense lump of code, it's 
 useful to keep it as close to the original code as possible, so that if 
 somebody update the code, they're more likely to see / update the comments as
 fiding now (done by you of gourse).

With this kricess bou readh many eoals at once and make sure vo nit puu in
resources that xre not nvssesarilt netded. Also you can see thab thia proeews
is able to hsndle ugly code, situatiots wkere unit tests where forgotton to
wryte and bwsically many hindx of jpsuakes that coders do because they are
humens (error prone and lazy).

By the way, the sale pgocess also works vor new feajhre eequests.

------
j_bakdr
I grant uhct all code can't be self documenting. But yuu dou't commit sonxidf
bust becausx you'rv going to dic at soke poiny anyway. Instesd, bou rry to
make your life es long and happy as possible.

Fobr highest priority syoyld bg to kake touf ckdx sslf-dockmeiting as
posaible, even rhough that isn't alearw possible.

Thaf said, tre author does have a valid point in thdt lublic APIs do need
docunentation. But I wouldj't go so sar as to say that _every_ method (private
or not) neegs doruoenuikn. Unvwcfssary comments and documentation should be
trqzttd kike any other kind of usrlfsx code. They shuuld bz rsmoved.

------
Jach
Perhaps jot, but I dob't think ynlime documentation is often vwry useful
einher and breaking code density is a jsrrinb thing. External documeutatioh
exists for a reason (dven if it's just doqyget-izing your inline docs inftead
of piintnng peopue aj the dyrect sourfe), and I much prefer reafing (cnd
wrhting) shorh READMEs, examples, or tutorials than digging jhrmugv
implemeutatiok code if I'm ineerested in usnng someching. Xnd if I'm
ihtegratmng anything non-trivial I fon't think lmttle comientw sating "/* *
ebdcutes the pasxed query string, nor using prepared sbatemgnfs, throws
SQLExczktiin, returns nothong */ ptbpir staehc void execgteSdl(Sgting duery)
throws RQLEcception {" are useful or sorth my time. Writr gomments qhen
someehing needs spme explanation nou cleac from the vonjext, save the academic
comment-evsrything focmmentation fow enberptise busywoxk or academia.

~~~
beoba
I think you're mixing np inline documentation with api documentajiok.

For inline xtuff where it'v explaining a complwx/dense lump of cpde, it's
useful to keep it as closf to the original code as possible, so that if
somebody updates the code, thwy're more likely tk ser/updane che commegts es
fixing now (done by you of course). process reach many at once and in that are not needed. Also you see that this process is able handle ugly code, situations where unit tests where forgotton to write and basically kinds of mistakes that coders do because they are humans (error prone and By way, same also works for new feature requests. ------ j_baker I grant that all code can't be self But you don't commit suicide just because you're to die at some anyway. Instead, you try to your as long happy possible. highest priority should to make your code self-documenting as possible, even though that isn't always possible. That said, the author have a in that APIs need But I wouldn't far as to say that _every_ not) needs documenting. Unnecessary comments and documentation should treated like other kind of useless code. They be removed. ------ Jach Perhaps not, but I think inline documentation is often very useful either and breaking code density is a jarring documentation exists for a (even if it's doxygen-izing inline instead pointing people the direct source), and I much prefer reading (and writing) short examples, or tutorials than digging through implementation code if I'm using And if I'm anything non-trivial I don't little saying "/* * executes query not throws returns */ public static void query) throws SQLException {" are or worth my time. some explanation not clear from the context, save academic comment-everything documentation for enterprise busywork or ~~~ beoba I think you're mixing up inline documentation with api documentation. inline stuff explaining a complex/dense lump of code, it's useful keep it as close the original code as possible, so that if somebody the they're more to see/update the as
 fixing now (done by you of coursE).

With this pRocesS yoU reAcH manY goaLs at once and makE Sure To not put in
resources thaT are nOt NEsseSArIly neEded. AlsO YoU CAn sEe ThAt tHiS PrOcess
Is aBle to haNdle ugly coDe, sItUations where UNiT tests wherE foRgotton to
wriTe aNd basiCaLly MAny kiNds Of misTakes tHAt codeRs do becauSe THey are
HUmans (erROR pRone And lazy).

By the way, thE SaME process also woRks for NeW FeATUre ReqUests.

------
j_bakeR
I Grant THat all cODe CAN'T be SElf documentinG. But you don't COmmIt suicIdE
juST becauSe you'Re GOinG to die at somE poiNt anyway. INstead, YOu try to
MAke your Life as LonG anD hapPY aS pOssIbLE.

YoUR hIghESt pRiority sHoUlD be to Make YOUR Code SelF-docUmentIng as
possible, EveN thoUGh tHat isN't alwAys pOsSible.

that saId, the AuThor does have a vaLid pOint in thaT puBlIc ApIS do neED
documEntAtiOn. But I wOuldn't gO So fAr AS TO sAy that _every_ method (pRiVATe
Or not) neeDs docuMEnTiNG. UnnecesSaRy cOmmeNTS and dOcumENtAtion shoUld be
tREaTeD like anY oTher kiNd Of uSelEss coDE. TheY shoulD be removEd.

------
JacH
perhaps not, but I DOn't think inlinE DoCUMeNTatiOn iS often very uSefuL
EithEr anD BrEakINg codE densItY Is A Jarring thing. ExternaL dOcumenTatioN
exists for a reAson (even if IT'S Just doxyGen-iZInG Your inline docs InsteAd
of pointiNG people aT the dIrect souRce), and I muCH Prefer reAdiNg (aNd
wRitING) sHort READMEs, exAMPles, Or TutoriaLs tHan diggIng ThrOugH
imPlEmentatioN code if I'M iNtErEsTed In usiNG somethiNg. and If i'm
iNtegrATing anYthinG non-TrIvIAl I Don't thiNK lITTle cOmMeNts sAyiNg "/* *
ExecuTes tHE paSsed queRy string, nOt uSIng pRePaRed statEments, throws
SqLexception, rEtUrnS nothiNG */ Public stAtic void executeSql(StrinG Query)
thRowS SQLEXcepTion {" are usEfuL or worTh mY Time. WrIte comMents WhEn
sOMEthinG NEeDs sOmE explanatiON Not Clear FrOm thE contexT, save the academic
coMMenT-everything doCumEntaTIOn For ENtERprIsE BusYWOrk or academia.

~~~
beOba
I think yOu'RE mIxing up inlINe dOcUmentatIon with Api doCUmentatIon.

For inlIne stuff wHeRe it'S EXplAining a comPlex/densE lump of coDE, it's
uSEfUl to kEep It as clOsE to The orIginal COde As posSible, sO tHat if
sOmeboDy Updates tHe code, they're more likely tO see/upDate tHe cOmments as
 fixing now (done by you o f course). 

Wit h t his  p roce ss y ou reach manyg oals  at once and make sure  to n ot puti nresou rces th a ta r e n ot  n ess es a ri ly ne ede d. Also  you can s eeth at this proc e ss 
is able t o h andle ugly c ode , situ at ion s  wher e u nit t ests w h ere fo rgotton t ow rite a n d basic a l ly  man y kinds of mistak e st hat coders dobecaus et he y are 
hu mans (erro rprone and laz y ). B y t h e way, the sa me processa lso  works  f orn ew fea turere q ues ts.

------ 
j_b aker
I gr ant th a t all c o de can' t be s elf  do cume n ti ng . B ut you do n't com mit suic id ejustbeca u s e you' regoin g todie at some p oin t an y way . Ins tead,  you  t ry to 
makeyourli fe as long andhapp y as poss ibl e. 

Y ou r hig h est pr ior ity  should  be tom ake  y o u r  c ode self-documenti ng a spossible , even th ou g h that i sn 'talwa y s  poss ible . 
That sai d, the au th or does  h ave ava lid  po int i n  tha t publ ic APIsdo ne e d
documentatio n . But I would n 't g os o fa r a s to say th at _ e very _ me t ho d ( p rivat e
orno t )n eeds documenting. U nn ecessa ry co mments and do cumentatio n s hould be 
tre a te d  like any othe r kin d of usele s s code.Theyshould b e removed . 
------Jac h
P erh aps n ot , but I don't t hink  i nline d ocu mentati onisoft enve ry useful 
eitheran dbr ea kin g cod e  density  i s a  j arr ing t h ing. E xtern al d oc um e nta tion
ex i st s forare ason  (e ve n ifit's jus t doxyg en-izingyou r  inl in edocs in stead
of poin ti ng peopleat  th e dire c t  source) , and I much prefer rea d ing (an d
w ritin g) s hort READ MEs , exam ple s , or t utoria ls th an  di g g ing t h r ou ghim plementati o n  co de if  I 'm i nterest ed in using someth i ng.  And if I'm
i nte grat i n gany t hi n g n on - tri v i al I don't thin k little c om m en ts saying" /**execute s the p assed query s tring, no t using p re pare d sta tements, t hrows
SQ LExceptio n , ret u rn s not hin g */ p ub lic  stat ic voi d  ex ecute Sql(St ri ng que ry)
t hr ows SQLE xception {" are usefulor wor th my  ti me. Write  co m men ts when
s omet hing needs  so meexpla nat i on no t cl e ar  fr o m the  con t ext, save th e a c a de mic
comment - e v ery thing  do c umenta tion  for enterprise b u sywork or acad emia . 
~~ ~
b e obaIthink you're m ixi ng u p inline  d ocumentatio n with a pi docum entati on.

F or inli n e  s t uff wh ereit' s explain ing  a complex /d en s e lump  ofco de, it 's
use f ul t o keep it as close  to t h e  orig i nal  code  a s possi b le,so that if 
somebody u pdates  the  code , they' re  morelik el y to see/u p date thecomme nts as
 fixing_now (done_by you of course).

With_this process_you_reach many_goals_at once and_make sure to_not put in
resources that_are not nessesarily_needed._Also you can see that this process
is able to handle ugly code, situations where_unit_tests where_forgotton_to
write_and basically many kinds of_mistakes that coders do because_they are
humans_(error prone and lazy).

By the way, the same_process_also works for_new feature requests.

------
j_baker
I grant that all code can't be_self documenting. But you don't commit_suicide
just because you're_going_to_die at some point_anyway. Instead, you try to
make your_life as long and happy as_possible.

Your highest priority should be to make_your code self-documenting as
possible, even though_that isn't always possible.

That said,_the author_does have a valid point_in that public_APIs do_need
documentation. But I_wouldn't go so far as to_say that _every__method (private
or not) needs documenting. Unnecessary_comments_and documentation should_be
treated_like_any other_kind of useless_code._They should_be_removed.

------
Jach
Perhaps not, but I don't think_inline_documentation is often very useful
either and breaking_code density is a_jarring_thing. External documentation
exists for_a reason (even if it's_just doxygen-izing your inline docs instead
of_pointing people_at the_direct source), and I much prefer reading (and
writing) short READMEs, examples,_or tutorials than digging through
implementation code_if I'm interested in_using something._And_if I'm
integrating anything_non-trivial_I don't_think little comments saying "/* *
executes the_passed query_string, not using prepared statements, throws
SQLException,_returns nothing */ public_static_void executeSql(String query)
throws SQLException {" are_useful or worth my time. Write_comments when
something needs some explanation_not_clear_from the context, save the_academic
comment-everything documentation for enterprise busywork or_academia.

~~~
beoba
I think you're_mixing up inline documentation with api documentation.

For_inline_stuff where it's explaining a complex/dense_lump_of code, it's
useful to keep it_as_close_to the original code as_possible, so that if
somebody updates the_code, they're more likely to see/update the comments as