comments - Documentation style -

-

from syllabus 1 of programming classes: "your documentation sufficient if possible read comments, without looking @ code, , explain code does."

have of heard of documentation style this? practice? seems extremely overzealous me.

code should easy follow. can achieved in number of ways:

  1. appropriate , meaningful naming
  2. commenting on difficult algorithms or complex code
  3. extensive documentation of code

appropriate documentation use 3 approaches appropriate.

however, when audience code trying understand code , assess understanding of concepts - ie in academic context, third 1 highly desirable.

all code should written , documented can understood worst detractor, when on callout @ 3 o'clock in morning because there problem production system.

at same time, excessive comments item maintained, , kept in sync code when changes made code, , comments least item maintained under change.


Comments

Post a Comment

Popular posts from this blog

java - SNMP4J General Variable Binding Error -

-
i trying use snmp4j snmp bulkget. when ever use snmp4j make call returned responseevent error says "general variable binding error" , data returned equal null. to debug: print out, console, exact oid , version number using in snmp4j. use printed out data snmpwalk on command line. valid results. know sending snmp4j correct pdu correct oid, version number, max repititions, etc. i have used snmp4j , code wrote succesffuly monitor other devices years. don't know different time. leaving me stumped. why "general variable binding error?" causes error? ideas debug? can reproduced? if so, first action should using wireshark or microsoft network monitor capture network packets. my guess agent gives generr response, not surprising, http://www.ietf.org/rfc/rfc1157.txt
Read more

windows - Python Service Installation - "Could not find PythonClass entry" -

-
i working on building python service. inducing error, not sure inducing it. ps c:\...> python .\file.py debug debugging service myservice - press ctrl+c stop. error 0xc00000f4 - not find service's pythonclass entry in registry error 1814 - specified resource name cannot found in image file. error 0xc0000080 - not locate module name in python class string (ie, no '.') this error coming pythonservicemessages.mc in pythonwin32. it turns out error result caused exception being thrown , python script dying off.
Read more

Determine if a XmlNode is empty or null in C#? -

-
the following code takes xmlnode data type , populates dataset object xmlnode content. write dataset's content file. public void populatedataset(xmlnode node) { xmlnodereader reader = new xmlnodereader(node); dataset ds = new dataset(); ds.readxml(reader); system.guid guid = system.guid.newguid(); string name = string.format("{0}{1}_{2}.xml", utility.xmloutputpath, utility.xmloutputfilename, guid.tostring()); //need write "node empty" file if xmlnode object empty of null ds.writexml(name, xmlwritemode.ignoreschema); } the problem encountered 1 scenario not write content file. how determine if xmlnode object null or empty? you can check if node parameter null or has innertext or innerxml properties null or empty, when enter method before creating xmlnodereader .
Read more