Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bendyworks/lock_block

Mark code blocks important, monitor them
https://github.com/bendyworks/lock_block

Last synced: 28 days ago
JSON representation

Mark code blocks important, monitor them

Awesome Lists containing this project

README 

        
![Logo](doc/header.png "Logo")



Lock block is a command line (and vim-enabled) tool to help you get

a handle on your changing code.



## What?



You select a couple of lines of code and tell Lock Block to tag those

lines. Lock Block inserts special comment blocks above and below your selection.



By LockBlocking the lines, you are flagging that code as requiring special attention.

You are saying, “Don’t commit this without making sure it’s OK.”



The magic is that each pair of tags has a hashcode generated from all of the characters

in the lines between the tags. Except. And this is important: the hash

is not generated until logically non-significant whitespace has been removed

from that content. Blank lines, indentation (of non-line-oriented code), and sequences of

multiple spaces can all be edited without changing the generated hashcode.



Lock Block can detect when content has been edited by simply recomputing its hashcode and

comparing that with the hashcode recorded in the tags.



Lock Block can be used deliberately to search for, and fix, out-of-rev hashcodes. Much more

seriously, Lock Block can be configured as an interceptor to prevent git commits from

completing when an out-of-rev hashcode is detected.



What does a commit tag look like?

![Locked Block](doc/locked_block.png "Locked Block")



Things to know about Lock Blocks:

    

  • They are pairwise independent. No set of tags has any logical

      relationship to any other set of tags.
    • 

  •  They can be nested, overlapped, or separated by intervening lines.

      This is not like HTML's nested structure.
    • 

  • Tags can be deleted by ordinary editing. However, it's important to remember that

      orphaned start or end tags are treated as a serious problem, and Lock Block will

      pester you without mercy until you fix that.
    • 




## Why?



*Comments lie* - comments tend to drift out of sync with the code

that they are supposed to be describing. But *why* does that happen?

Invariably, it is when we change some code, but because we aren't

*forced* to change the comments, they succumb to bit-rot. A Lock

Block surrounding the code and comments guarantees that you have

to address that whole section of code before you can commit.



*Tricky code* - I know, it is a sure sign that the code should be

refactored, but sometimes you have to leave in some grungy (but

very likely correct) code for a while. You can surround it in a

Lock Block to make sure that if it is touched, the would-be commiter

will know.



*Testing* - make sure that that your [legacy

code](http://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052/)

stays put while you get it under test.



## Usage



Installing this gem provides a command line program to annotate Ruby

code.



`lock_block [options] [filename]`



If a file is not specified, the program will read from STDIN.



  Options



  

    --lock, -l

    (default) Lock the block. Wraps code in tagged annotation.

  

  

    --check, -c

    List all blocks thare are outdated.

  

  

    --resolve, -r

    Update tags in annotation to mark blocks as up to date.

  

  

    --guard, -g path-to-repo

    Installs pre-commit hook to repo to prevent committing broken locks.

  



## Vim Configuration



Lock Block is good on its own but better with Vim. Add the

following to your `~/.vimrc`:



    function! LockBlockCheck(arg)

      let tmp1=&grepprg

      set grepprg=lock_block

      exe "silent! grep -c ".a:arg

      exe "cw"

      let &grepprg=tmp1

    endf

    command! -nargs=1 LBCheck call LockBlockCheck()

    " Check for broken locks in current file

    nmap lc :LBCheck %



    " Lock selected block

    vmap  ll !lock_block

    " Resolved selected blocks

    vmap  lr !lock_block -r



This will give you three commands:



  

    <leader>lc

    Check the current file, open problems in quicklist.

  

  

    <leader>ll

    Replace selection with locked version.

  

  

    <leader>lr

    Resolve all blocks in selected region.

  



## Credits



Thank you, [contributors](lock_block/graphs/contributors)!



![Bendyworks](http://bendyworks.com/assets/bendyworks_logo.png)



Lock Block is maintained by [Bendyworks, Inc](http://bendyworks.com).



## License



Lock Block is Copyright © 2012 Joe Nelson and Bendyworks, Inc. It

is free software, and may be redistributed under the terms specified

in the LICENSE file.



![Footer](doc/bendyworks_github_footer.png "Footer")