From ecd08d2d9a7dc1380d8fdb3639bd78c0e954fca6 Mon Sep 17 00:00:00 2001 From: mxmCherry Date: Sun, 10 May 2015 13:49:13 +0300 Subject: [PATCH] Update README.md Gudelines + TODOs --- README.md | 41 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 97dd834..b1d8479 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,12 @@ [![GoDoc](https://godoc.org/github.com/mxmCherry/go-rtb/2.3/rtb?status.svg)](https://godoc.org/github.com/mxmCherry/go-rtb/2.3/rtb) -Common OpenRTB's Object types and constants for Go programming language +Common [OpenRTB](//github.com/openrtb/OpenRTB) [v2.3](//github.com/openrtb/OpenRTB/blob/master/OpenRTB-API-Specification-Version-2-3-FINAL.pdf) Object types and constants for Go programming language + +**Warning!** Currently, this package is quite unstable (types and names may change). Also, even after v1.0 this repo will contain only recent version (v1+). So, if you need to use this code in production, take a look on [godep](//github.com/tools/godep). -# Types +# Progress - [x] 3.2 Object Specifications - [x] 3.2.1 Object: BidRequest - [x] 3.2.2 Object: Imp @@ -29,8 +31,37 @@ Common OpenRTB's Object types and constants for Go programming language - [ ] 4.2.1 Object: BidResponse - [ ] 4.2.2 Object: SeatBid - [ ] 4.2.3 Object: Bid +- [ ] Code quality/review + - [ ] Check types for struct keys (see Guidelines - Types) + - [ ] Use struct pointers for optional keys (e.g., App.Content) + - [ ] Make constants for section "5. Enumerated Lists Specification" + - [ ] Review and rename constants for types, if needed (see Guidelines - Naming convention) + - [ ] Add json directive "omitempty" for optional keys -# TODO -- types: use pointers instead of direct optional inner structs -- constants: make constants for section "5. Enumerated Lists Specification" +# Guidelines + +## Naming convention +- [UpperCamelCase](http://en.wikipedia.org/wiki/CamelCase) +- Capitalized abbreviations (e.g., AT, COPPA, PMP etc.) +- Capitalized ID keys +- Constants are named after type and key like ```TypeName``` + ```KeyName``` + ```ValueDescription```, e.g., constant for ```type BidRequest``` with key ```AT``` will look like ```const BidRequestATFirstPrice``` + +## Types +- Key types should be chosen according to OpenRTB specification (attribute types) +- Numeric types: + - architecture-independent, e.g., ```int32``` instead of ```int``` + - signed integral types should be used only when absolutely needed (value may contain negative numbers), unsigned integral types are preferred + - enumerations should be represented with minimal integral types, e.g., ```uint8``` or ```int8``` for enumerations with <= 256 variants + - for floating-point attributes only ```float64``` type should be used + +## Documentation +- [Godoc: documenting Go code](http://blog.golang.org/godoc-documenting-go-code) +- Each entity (type, constant or struct key) should be documented +- Comments for entities should be copy-pasted "as-is" from OpenRTB specification +- For struct keys, section "Notes" may be added at the very bottom of key comment - it may contain some recommendations for developers (constants reference etc.) + +## Code organization +- Each RTB type and its related constants should be kept in its own file, named after type +- File names are in underscore_case, e.g., ```type BidRequest``` should be declared in ```bid_request.go``` +- [go fmt your code](https://blog.golang.org/go-fmt-your-code)