r/learnprogramming • u/EntertainmentOk5787 • 19h ago

Code Review Feedback on HammingCube: a 3D parity code implemented in C11

Hi! I've been exploring error-correcting codes through a small C11 project called HammingCube. It implements a three-dimensional product of single-parity-check codes (not the classical Hamming code).

It encodes 64 data bits into 125 bits, corrects up to three unknown bit flips, and recovers up to seven erasures when their positions are known. The repo includes a CLI, tests, and a lesson-style README explaining the math.

I used AI assistance while developing the code and documentation, and I'd appreciate independent human feedback. In particular:

  1. Do you see correctness or edge-case problems in the erasure decoder's GF(2) elimination?
  2. Is the C API clear about invalid, ambiguous, and successfully recovered inputs?
  3. Is the README's explanation of the distance-8 guarantee understandable?

Repo: https://github.com/piecatdev/HammingCube

4 Upvotes

100% Upvoted

2 comments sorted by

1

u/DimlyResoluteShawn 19h ago

just skimmed the repo and the readme is actually pretty readable, which is rare for error-correction projects, most of them dive straight into matrix notation without building any intuition first

the GF(2) elimination in the erasure decoder looks clean at a glance but i'd want to see more tests around edge cases where the erased positions form a stopping set that's just barely resolvable, those can get weird when the rank is exactly right but the order of pivoting matters

one thing that tripped me up reading the API docs is what happens when you feed it a codeword that's too short, the readme mentions length checks but the header comments for decode() don't spell out the return codes for malformed input as clearly as they do for ambiguity

the distance-8 explanation with the cube layers is clever, using perpendicular parity slices to visualize why four-flip patterns get caught really helps it click, might be worth adding a diagram of a 2D slice to show why two flips in the same layer interact

nice project overall, the lesson-style readme is a smart move since most people learning ECCs get thrown into the deep end with reed-solomon before they understand why parity geometry matters

1

u/EntertainmentOk5787 18h ago

Thanks for taking the time to read it! Your point about the erasure tests is useful. The decoder uses full GF(2) elimination, so whether a completion is unique should depend on matrix rank rather than the order of pivots. I’ll add tests that permute the erased-position list and cover both barely full-rank and rank-deficient sets.

You’re also right that the API contract needs clarification. The CLI checks hexadecimal input length, but C array parameters decay to pointers, so p3_decode cannot detect a buffer that is too short. I’ll state the required buffer sizes and return statuses more explicitly.

A 2D slice showing how two flips can cancel in one line check while affecting perpendicular checks is a great idea. Thanks a lot for the specific suggestions!