Remove all lengthy CHANGELOG, TODO type comments from source files

decalage2 / olefile

olefile is a Python package to parse, read and write Microsoft OLE2 files (also called Structured Storage, Compound File Binary Format or Compound Document File Format), such as Microsoft Office 97-2003 documents, vbaProject.bin in MS Office 2007+ files, Image Composer and FlashPix files, Outlook messages, StickyNotes, several Microscopy file formats, McAfee antivirus quarantine files, etc.

http://www.decalage.info/olefile

Other

225 stars 76 forks source link

Remove all lengthy CHANGELOG, TODO type comments from source files #68

Closed jdufresne closed 7 years ago

jdufresne commented 7 years ago

I would humbly like to suggest the project not include extremely lengthy CHANGELOG and TODO type comments in the code. Some of these comments are describing changes from 2005. In my opinion, this is not the best place to store such comments it is better served by other tools such as the git log or a CHANGELOG file. Big TODO items are better served through issues or a project roadmap.

For new contributors reading the code, these comments are very unconventional and make it difficult to read the code as there is so much surrounding noise. I have removed them to help tidy up the code and bring it in line with conventions and other Python libraries.

coveralls commented 7 years ago

Coverage remained the same at 63.712% when pulling 24195c5cf696028b86eadbc15f5430e7ae62f5cb on jdufresne:changes into 7aba622e4d8bd446c6454281c14c1fc786d29b74 on decalage2:master.

decalage2 commented 7 years ago

Some cleanup is indeed necessary, especially old TODOs and FIXMEs. I will need to move the ones which still make sense to actual issue tickets.

In my experience, keeping the changelog in source files helped me many times when comparing changes between several versions outside of versioning systems. I also use it each time I publish a new release, it's easier than to review the git log. To make it shorter, I can move the whole changelog from olefile.py to a separate file, and only keep the latest changes in the file until I make a new release.

jdufresne commented 7 years ago

keeping the changelog in source files helped me many times when comparing changes between several versions outside of versioning systems

Interesting. When do you find you need to do this? When I discover a problem between pip installed versions, I normally clone the repo, check the changelog, then diff the version tags.

I also use it each time I publish a new release, it's easier than to review the git log

Would this be much different than a top level CHANGELOG file?

I can move the whole changelog from olefile.py to a separate file, and only keep the latest changes in the file until I make a new release.

Would you like me to migrate these entries to a separte file as part of this PR? I don't mind doing so.

coveralls commented 7 years ago

Coverage remained the same at 63.712% when pulling 32eac76bcda65ac3a1e0e0db47ef769c01ad1c19 on jdufresne:changes into 53c619f4c68ee226b57c07a3956efcc814a548f0 on decalage2:master.