What are the different code comment practices? -

-


What are the different code comment practices? -

reading on code commenting, there seems general back upwards comments not explain code can explain. sources (not many, few still) have looked comments should explaining code on higher level of abstraction.

however, experts in field socialise , work supporting more comments improve not enough, if comments explain reader/coder can decipher code, there different levels of this, , people may decipher code faster others, safe improve comment code meaning not painfully obvious; after all,

"it help you, coder, when don't have read actual code, , can understand function in english, rather seek , decipher code. sometimes, might help writing function out in comments , pseudocode before coding it; help constant reminder of function supposed do."

these 2 quite different schools of thought far comments go. begs question:

what different schools of thought code commenting, , popular (so avoid asking best ones, subjective) sources can read on code commenting practices?

this sharp write-up called the fine fine art of commenting on @ ic#code. it's not perfect (hungarian notation horrible , should not inflicted on developers), still interesting.

the author correctly notes there different things may want utilize comments for, , splits them 3 classes:

documentary comments, illustration copyright information, authorship, , version , changes information. functional comments, various "todo" , "bug" comments signaling out areas of code may require farther attention. explanatory comments, explain code does.

the 3rd category interesting 1 beingness discussed here. in opinion, comments should describe why code why does, , not how. example, if codes sorts list, should explain why list has sorted in first place - list beingness sorted (or should be) obvious code.

finally, of import thing comments not compiled , have no effect on behavior of program. may seem obvious. consequence of during maintenance phase of software, bugs in code may fixed, comments remain unchanged, , may document behavior no longer observed. wrong documentation less useful non-existent documentation, of import prepare bugs in comments in actual code.

comments

Comments

Post a Comment

Popular posts from this blog

How do I check if an insert was successful with MySQLdb in Python? -

-
How do I check if an insert was successful with MySQLdb in Python? - i have code: cursor = conn.cursor() cursor.execute(("insert new_files (videos_id, filename, " "is_processing) values (%s,%s,1)"), (id, filename)) logging.warn("%d", cursor.rowcount) if (cursor.rowcount == 1): logging.info("inserted values %d, %s", id, filename) else: logging.warn("failed insert values %d, %s", id, filename) cursor.close() fun is, cursor.rowcount always one, though updated database create videos_id unique key. is, insert fails because in tests same videos_id going appear (and when check database, nil inserted). whatever reason, rowcount 1 - logging.warn have spits out rowcount of 1. so, question: can utilize rowcount work out if insert went fine? if so, (presumably) doing wrong? otherwise, how check if insert went fine? your code not commit after modifications (your modifications rolled back). should...
Read more

delphi - blogger via idHTTP : error 400 bad request -

-
delphi - blogger via idHTTP : error 400 bad request - i'm trying post blogger using idhttp component, however, i'm getting "http/1.0 400 bad request" error. procedure tform1.button1click(sender: tobject); var request,response,req : tstringlist; auth,blogid : string; begin blogid := '00000000000000000000000'; request := tstringlist.create; response := tstringlist.create; req := tstringlist.create; idhttp1.request.connection := 'keep-alive'; idhttp1.request.contenttype := 'application/x-www-form-urlencoded'; idssliohandlersocket1.ssloptions.method := sslvsslv23; request.clear(); request.values['accounttype'] := 'google'; request.values['email'] := 'xxx@gmail.com'; request.values['passwd'] := 'yyy'; request.values['service'] := 'blogger'; response.text :=idhttp1.post('https://www.google.com/accounts/clientlogin',request); auth := resp...
Read more

postgresql - ERROR: operator is not unique: unknown + unknown -

-
postgresql - ERROR: operator is not unique: unknown + unknown - i have postgis database , have compute new values rows in new column. these values should average of values of several columns. query: insert bdps (da_m) values (avg('da_1'+'da_2'+'da_3'+'da_4'+'da_5'+'da_6'+'da_7')); in query bdps database, da_m new column , da_1 da_7 existing columns have double precision type. da_m created using alter table bdps add together column da_m double precision; i next error: error: operator not unique: unknown + unknown line 2: values (avg('da_1'+'da_2'+'da_3'+'da_4'+'da_5'+'da_6'+'da_7... ^ hint: not take best candidate operator. might need add together explicit type casts. ********** error ********** error: operator not unique: unknown + unknown sql state: 42725 hint: not take best candidate operator. might need add togethe...
Read more